Merchants API

The API for managing merchants and merchant-related data in the Pushpay platform


Get Merchant

GET /v1/merchant/{merchantKey}

Retrieves the details of the merchant including the reference definitions

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

Required Scopes

Scope Description
read Read-only access to resources owned by the subject claim of the token

Retrieve details of merchant by its key

Request

GET /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "homeCountry": "NZ", "visibility": "Visible", "status": "Active", "version": 50, "key": "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ", "handle": "widgetinc", "name": "Widgets Inc", "address": "123 Summer Grove", "location": { "latitude": -36.8567852, "longitude": 174.7583516 }, "paymentParameters": { "currency": "USD", "payButtonLabel": "Pay", "limits": { "min": 10.0, "max": 15000.0 }, "paymentPlaceholder": "e.g. 50.00", "mustBePaidInSafari": false }, "referenceDefinitions": [ { "id": 3, "order": 0, "valueType": "Text", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Full Name", "placeholder": "Full Name", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Email", "placeholder": "Email", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Phone", "placeholder": "Phone Number" }, { "id": 123, "order": 0, "valueType": "SingleSelect", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Widget Color", "choices": [ { "label": "Blue", "value": "bl", "order": 0, "isDefault": false }, { "label": "Green", "value": "grn", "order": 0, "isDefault": false }, { "label": "Black", "value": "blk", "order": 0, "isDefault": true } ] } ], "logo": { "android": { "size": 150, "href": "https://pushpay.com/images/merchantlogo/50/123/1" }, "iOS": { "size": 108, "href": "https://pushpay.com/images/merchantlogo/50/123/0" }, "admin": { "size": 80, "href": "https://pushpay.com/images/merchantlogo/50/123/2" }, "account": { "size": 140, "href": "https://pushpay.com/images/merchantlogo/50/123/3" } }, "colors": { "primary": "#cf150a" }, "organizationKey": "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA", "v3OrganizationKey": "df21b3c4e4303167ec70143c8ca1dd78", "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" }, "merchantsettlements": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/settlements" }, "merchantBatches": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/batches" } } }
<?php
/*
	Example 1
	Retrieve details of merchant by its key
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Retrieve details of merchant by its key
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# Retrieve details of merchant by its key
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Retrieve details of merchant by its key
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var requestUrl = string.Format("/v1/merchant/{0}", merchantKey);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Retrieve details of a non-existent merchant

Request

GET /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

Response

Status 404 (Not Found)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "message": "Merchant does not exist" }
<?php
/*
	Example 2
	Retrieve details of a non-existent merchant
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 2
 * Retrieve details of a non-existent merchant
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 2
# Retrieve details of a non-existent merchant
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example2
	{

		/// <summary>
		///	Example 2
		/// </summary>
		/// <remarks>
		///	Retrieve details of a non-existent merchant
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var requestUrl = string.Format("/v1/merchant/{0}", merchantKey);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Retrieve details of merchant with a custom HPP primary color

Request

GET /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "homeCountry": "NZ", "visibility": "Visible", "status": "Active", "version": 50, "key": "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ", "handle": "widgetinc", "name": "Widgets Inc", "address": "123 Summer Grove", "location": { "latitude": -36.8567852, "longitude": 174.7583516 }, "paymentParameters": { "currency": "USD", "payButtonLabel": "Pay", "limits": { "min": 10.0, "max": 15000.0 }, "paymentPlaceholder": "e.g. 50.00", "mustBePaidInSafari": false }, "referenceDefinitions": [ { "id": 3, "order": 0, "valueType": "Text", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Full Name", "placeholder": "Full Name", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Email", "placeholder": "Email", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Phone", "placeholder": "Phone Number" }, { "id": 123, "order": 0, "valueType": "SingleSelect", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Widget Color", "choices": [ { "label": "Blue", "value": "bl", "order": 0, "isDefault": false }, { "label": "Green", "value": "grn", "order": 0, "isDefault": false }, { "label": "Black", "value": "blk", "order": 0, "isDefault": true } ] } ], "logo": { "android": { "size": 150, "href": "https://pushpay.com/images/merchantlogo/50/123/1" }, "iOS": { "size": 108, "href": "https://pushpay.com/images/merchantlogo/50/123/0" }, "admin": { "size": 80, "href": "https://pushpay.com/images/merchantlogo/50/123/2" }, "account": { "size": 140, "href": "https://pushpay.com/images/merchantlogo/50/123/3" } }, "colors": { "primary": "#000539" }, "organizationKey": "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA", "v3OrganizationKey": "df21b3c4e4303167ec70143c8ca1dd78", "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" }, "merchantsettlements": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/settlements" }, "merchantBatches": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/batches" } } }
<?php
/*
	Example 3
	Retrieve details of merchant with a custom HPP primary color
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 3
 * Retrieve details of merchant with a custom HPP primary color
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 3
# Retrieve details of merchant with a custom HPP primary color
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example3
	{

		/// <summary>
		///	Example 3
		/// </summary>
		/// <remarks>
		///	Retrieve details of merchant with a custom HPP primary color
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var requestUrl = string.Format("/v1/merchant/{0}", merchantKey);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Delete Webhook

DELETE /v1/merchant/{merchantKey}/webhook/{token}

Deletes a webhook - any queued webhook messages will still be delivered after the webhook subscription is removed, but no new webhook messages will be queued for this webhook subscription

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

token string

The textual token that uniquely identifies the webhook subscription

Required Scopes

Scope Description
manage_webhooks Manage webhooks for a merchant - this scope will soon be deprecated, so instead use merchant:manage_webhooks
merchant:manage_webhooks Manage webhooks for a merchant

Delete a webhook identified by its token

Request

DELETE /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw

Headers

Name Value Description
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

token FGS7rjGWr02KN8d4AGIRMw path

The textual token that uniquely identifies the webhook subscription

Response

Status 204 (No Content)

Code Samples

No JSON content

<?php
/*
	Example 1
	Delete a webhook identified by its token
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$token = 'FGS7rjGWr02KN8d4AGIRMw';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey/webhook/$token";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Delete a webhook identified by its token
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String token = "FGS7rjGWr02KN8d4AGIRMw";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey + "/webhook/" + token;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		httpConnection.setRequestMethod("DELETE");
		httpConnection.setDoOutput(true);
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		httpConnection.disconnect();
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		httpConnection.setRequestMethod("DELETE");
		httpConnection.setDoOutput(true);
		return httpConnection;
	}
}
# Example 1
# Delete a webhook identified by its token
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set token="FGS7rjGWr02KN8d4AGIRMw"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/webhook/%token%"

curl -i -H "Authorization: Bearer %oAuthToken%" -X DELETE %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Delete a webhook identified by its token
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var token = "FGS7rjGWr02KN8d4AGIRMw";
				var requestUrl = string.Format("/v1/merchant/{0}/webhook/{1}", merchantKey, token);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.DeleteAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Get Webhook

GET /v1/merchant/{merchantKey}/webhook/{token}

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

token string

The textual token that uniquely identifies the webhook subscription

Required Scopes

Scope Description
manage_webhooks Manage webhooks for a merchant - this scope will soon be deprecated, so instead use merchant:manage_webhooks
merchant:manage_webhooks Manage webhooks for a merchant

Retrieve a single webhook for a merchant identified by its token

Request

GET /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

token FGS7rjGWr02KN8d4AGIRMw path

The textual token that uniquely identifies the webhook subscription

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw" }, "merchant": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" } } }
<?php
/*
	Example 1
	Retrieve a single webhook for a merchant identified by its token
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$token = 'FGS7rjGWr02KN8d4AGIRMw';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey/webhook/$token";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Retrieve a single webhook for a merchant identified by its token
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String token = "FGS7rjGWr02KN8d4AGIRMw";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey + "/webhook/" + token;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# Retrieve a single webhook for a merchant identified by its token
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set token="FGS7rjGWr02KN8d4AGIRMw"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/webhook/%token%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Retrieve a single webhook for a merchant identified by its token
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var token = "FGS7rjGWr02KN8d4AGIRMw";
				var requestUrl = string.Format("/v1/merchant/{0}/webhook/{1}", merchantKey, token);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Update Webhook

PUT /v1/merchant/{merchantKey}/webhook/{token}

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

token string

The textual token that uniquely identifies the webhook subscription

Required Scopes

Scope Description
manage_webhooks Manage webhooks for a merchant - this scope will soon be deprecated, so instead use merchant:manage_webhooks
merchant:manage_webhooks Manage webhooks for a merchant

Update the webhooks configuration

Request

PUT /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw

Headers

Name Value Description
Content-Type application/json
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

token FGS7rjGWr02KN8d4AGIRMw path

The textual token that uniquely identifies the webhook subscription

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Body

{ "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ] }

Response

{ "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw" }, "merchant": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" } } }
<?php
/*
	Example 1
	Update the webhooks configuration
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$token = 'FGS7rjGWr02KN8d4AGIRMw';
$requestBody = '{
  "target": "http://widgets.com/payment/statuschange",
  "eventTypes": [
    "anticipated_payment_status_changed"
  ]
}';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey/webhook/$token";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Content-Type: application/json",
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Update the webhooks configuration
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String token = "FGS7rjGWr02KN8d4AGIRMw";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey + "/webhook/" + token;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		httpConnection.setRequestMethod("PUT");
		httpConnection.setDoOutput(true);
		String requestBody = "{" + 
			"  \"target\": \"http://widgets.com/payment/statuschange\"," + 
			"  \"eventTypes\": [" + 
			"    \"anticipated_payment_status_changed\"" + 
			"  ]" + 
			"}";
		OutputStream outputStream = httpConnection.getOutputStream();
		outputStream.write(requestBody.getBytes("UTF-8"));
		outputStream.close();
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Content-Type", "application/json");
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		httpConnection.setRequestMethod("PUT");
		httpConnection.setDoOutput(true);
		return httpConnection;
	}
}
# Example 1
# Update the webhooks configuration
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set token="FGS7rjGWr02KN8d4AGIRMw"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/webhook/%token%"
set requestBody="{\"target\": \"http://widgets.com/payment/statuschange\",\"eventTypes\": [\"anticipated_payment_status_changed\"]}"

curl -i -H "Content-Type: application/json" -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" -d %requestBody% -X PUT %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Update the webhooks configuration
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var token = "FGS7rjGWr02KN8d4AGIRMw";
				var requestUrl = string.Format("/v1/merchant/{0}/webhook/{1}", merchantKey, token);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var jsonString = JsonConvert.SerializeObject(new {
					  target = "http://widgets.com/payment/statuschange",
					  eventTypes = new [] {
					    "anticipated_payment_status_changed"
					  }});
				var body = new StringContent(jsonString, Encoding.UTF8, "application/json");
				var requestMessage = new HttpRequestMessage(HttpMethod.Put, requestUrl) { Content = body };

				var httpResponse = await client.SendAsync(requestMessage);

				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Get Merchant Webhooks

GET /v1/merchant/{merchantKey}/webhooks

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

Required Scopes

Scope Description
manage_webhooks Manage webhooks for a merchant - this scope will soon be deprecated, so instead use merchant:manage_webhooks
merchant:manage_webhooks Manage webhooks for a merchant

Get all webhooks registered for a merchant

Request

GET /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhooks

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "items": [ { "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw" }, "merchant": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" } } }, { "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw" }, "merchant": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" } } } ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhooks" } } }
<?php
/*
	Example 1
	Get all webhooks registered for a merchant
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey/webhooks";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Get all webhooks registered for a merchant
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey + "/webhooks";

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# Get all webhooks registered for a merchant
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/webhooks"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Get all webhooks registered for a merchant
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var requestUrl = string.Format("/v1/merchant/{0}/webhooks", merchantKey);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Create Webhook

POST /v1/merchant/{merchantKey}/webhooks

Path (URL) Parameters

Name Type Description
merchantKey string

The unique key of the merchant - a case-sensitive series of characters

Required Scopes

Scope Description
manage_webhooks Manage webhooks for a merchant - this scope will soon be deprecated, so instead use merchant:manage_webhooks
merchant:manage_webhooks Manage webhooks for a merchant

Example 1

Create a new webhook for a merchant

Request

POST /v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhooks

Headers

Name Value Description
Content-Type application/json
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
merchantKey MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ path

The unique key of the merchant - a case-sensitive series of characters

Response

Status 201 (Created)

Headers

Name Value Description
Location https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw
Content-Type application/hal+json; charset=utf-8

Code Samples

Body

{ "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ] }

Response

{ "target": "http://widgets.com/payment/statuschange", "eventTypes": [ "anticipated_payment_status_changed" ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/webhook/FGS7rjGWr02KN8d4AGIRMw" }, "merchant": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" } } }
<?php
/*
	Example 1
	Create a new webhook for a merchant
*/
$merchantKey = 'MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ';
$requestBody = '{
  "target": "http://widgets.com/payment/statuschange",
  "eventTypes": [
    "anticipated_payment_status_changed"
  ]
}';
$url = "https://api.pushpay.com/v1/merchant/$merchantKey/webhooks";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Content-Type: application/json",
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
// Store the link to the created item in a variable
$selfLink = $jsonResponse['_links']['self']['href'];
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Create a new webhook for a merchant
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
		String urlString = "https://api.pushpay.com/v1/merchant/" + merchantKey + "/webhooks";

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		httpConnection.setRequestMethod("POST");
		httpConnection.setDoOutput(true);
		String requestBody = "{" + 
			"  \"target\": \"http://widgets.com/payment/statuschange\"," + 
			"  \"eventTypes\": [" + 
			"    \"anticipated_payment_status_changed\"" + 
			"  ]" + 
			"}";
		OutputStream outputStream = httpConnection.getOutputStream();
		outputStream.write(requestBody.getBytes("UTF-8"));
		outputStream.close();
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		// Store the link to the created item in a variable
		URL selfLink = response._links.self.href;
		httpConnection.disconnect();
	}

	class Response {
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Content-Type", "application/json");
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		httpConnection.setRequestMethod("POST");
		httpConnection.setDoOutput(true);
		return httpConnection;
	}
}
# Example 1
# Create a new webhook for a merchant
set oAuthToken=%1
set merchantKey="MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ"
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/webhooks"
set requestBody="{\"target\": \"http://widgets.com/payment/statuschange\",\"eventTypes\": [\"anticipated_payment_status_changed\"]}"

curl -i -H "Content-Type: application/json" -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" -d %requestBody% -X POST %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Create a new webhook for a merchant
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ";
				var requestUrl = string.Format("/v1/merchant/{0}/webhooks", merchantKey);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var jsonString = JsonConvert.SerializeObject(new {
					  target = "http://widgets.com/payment/statuschange",
					  eventTypes = new [] {
					    "anticipated_payment_status_changed"
					  }});
				var body = new StringContent(jsonString, Encoding.UTF8, "application/json");
				var requestMessage = new HttpRequestMessage(HttpMethod.Post, requestUrl) { Content = body };

				var httpResponse = await client.SendAsync(requestMessage);

				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Search Merchants

GET /v1/merchants

You can find merchants matching one or more parameters for:

  • country (Country, valid values are NZ, AU, CA or US currently).
  • name (Full or partial name)
  • handle (the full handle for a merchant)

Note: Unfiltered requests will return merchants of Status = Active and Visibility = Visible

Query string (URL) parameters

Name Type Description
name string

One or more terms between spaces which will each be matched partially against the name of the merchant

handle string

The unique text 'handle' assigned to the merchant

country string

The country the Merchant resides within

visibility string

Only include merchant listings matching the specified visibility - Visible/Hidden

status string

Only include merchant listings matching the specified status - Active/Pending/Closed

page integer

The page parameter (Note: page numbering starts at 0)

pageSize integer

The page size parameter (Note: default page size is 25)

Required Scopes

Scope Description
read Read-only access to resources owned by the subject claim of the token

Search for merchants

Request

GET /v1/merchants?country=US&name=church&page=0&pageSize=25

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
name church query

One or more terms between spaces which will each be matched partially against the name of the merchant

handle query

The unique text 'handle' assigned to the merchant

country US query

The country the Merchant resides within

visibility query

Only include merchant listings matching the specified visibility - Visible/Hidden

status query

Only include merchant listings matching the specified status - Active/Pending/Closed

page 0 query

The page parameter (Note: page numbering starts at 0)

pageSize 25 query

The page size parameter (Note: default page size is 25)

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "page": 0, "pageSize": 25, "total": 1, "totalPages": 1, "items": [ { "homeCountry": "NZ", "visibility": "Visible", "status": "Active", "version": 50, "key": "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ", "handle": "widgetinc", "name": "Widgets Inc", "address": "123 Summer Grove", "location": { "latitude": -36.8567852, "longitude": 174.7583516 }, "paymentParameters": { "currency": "USD", "payButtonLabel": "Pay", "limits": { "min": 10.0, "max": 15000.0 }, "paymentPlaceholder": "e.g. 50.00", "mustBePaidInSafari": false }, "referenceDefinitions": [ { "id": 3, "order": 0, "valueType": "Text", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Full Name", "placeholder": "Full Name", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Email", "placeholder": "Email", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Phone", "placeholder": "Phone Number" }, { "id": 123, "order": 0, "valueType": "SingleSelect", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Widget Color", "choices": [ { "label": "Blue", "value": "bl", "order": 0, "isDefault": false }, { "label": "Green", "value": "grn", "order": 0, "isDefault": false }, { "label": "Black", "value": "blk", "order": 0, "isDefault": true } ] } ], "logo": { "android": { "size": 150, "href": "https://pushpay.com/images/merchantlogo/50/123/1" }, "iOS": { "size": 108, "href": "https://pushpay.com/images/merchantlogo/50/123/0" }, "admin": { "size": 80, "href": "https://pushpay.com/images/merchantlogo/50/123/2" }, "account": { "size": 140, "href": "https://pushpay.com/images/merchantlogo/50/123/3" } }, "colors": { "primary": "#cf150a" }, "organizationKey": "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA", "v3OrganizationKey": "df21b3c4e4303167ec70143c8ca1dd78", "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" }, "merchantsettlements": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/settlements" }, "merchantBatches": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/batches" } } } ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchants?country=US&name=church" } } }
<?php
/*
	Example 1
	Search for merchants
*/
$name = 'church';
$country = 'US';
$page = 0;
$pageSize = 25;
$url = "https://api.pushpay.com/v1/merchants?name=$name&country=$country&page=$page&pageSize=$pageSize";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
// If there is a next page, store the link to it in a variable
if (array_key_exists('next', $jsonResponse['_links'])) {
	$nextLink = $jsonResponse['_links']['next']['href'];
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Search for merchants
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String name = "church";
		String country = "US";
		int page = 0;
		int pageSize = 25;
		String urlString = "https://api.pushpay.com/v1/merchants?name=" + name + "&country=" + country + "&page=" + page + "&pageSize=" + pageSize;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		// Store the link to the next page in a variable
		URL nextLink = response._links.next.href;
		httpConnection.disconnect();
	}

	class Response {
		public int page { get; set; }
		public int pageSize { get; set; }
 		public int total { get; set; }
 		public int totalPages { get; set; }
 		public Response[] items { get; set; }
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
		public Link next;
		public Link prev;
		public Link first;
		public Link last;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# Search for merchants
set oAuthToken=%1
set name="church"
set country="US"
set page=0
set pageSize=25
set url="https://api.pushpay.com/v1/merchants?name=%name%&country=%country%&page=%page%&pageSize=%pageSize%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Search for merchants
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var name = "church";
				var country = "US";
				var page = 0;
				var pageSize = 25;
				var requestUrl = string.Format("/v1/merchants?name={0}&country={1}&page={2}&pageSize={3}", 
					name, country, page, pageSize);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					var nextLink = response.Links.Next;
					Console.WriteLine(nextLink);
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		public int Page { get; set; }
		public int PageSize { get; set; }
 		public int Total { get; set; }
 		public int TotalPages { get; set; }
 		public Response[] Items { get; set; }
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
		public Link Next { get; set; }
		public Link Prev { get; set; }
		public Link First { get; set; }
		public Link Last { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

List In-Scope Merchants

GET /v1/merchants/in-scope

You can find merchants the client's scope applies to - you can further filter this list by using one or more parameters for:

  • country (Country, valid values are NZ, AU, CA or US currently).
  • name (Full or partial name of a merchant listing)
  • handle (the full handle for a merchant listing)
  • visibility (if the merchant listings are visible or hidden)
  • status (if the merchant listings are active, closed or pending)

Note: Unfiltered requests will return merchants of Status = Active/Pending/Closed and Visibility = Visible/Hidden

Query string (URL) parameters

Name Type Description
name string

One or more terms between spaces which will each be matched partially against the name of the merchant

handle string

The unique text 'handle' assigned to the merchant

country string

The country the Merchant resides within

visibility string

Only include merchant listings matching the specified visibility - Visible/Hidden

status string

Only include merchant listings matching the specified status - Active/Pending/Closed

page integer

The page parameter (Note: page numbering starts at 0)

pageSize integer

The page size parameter (Note: default page size is 25)

Required Scopes

Scope Description
read Read-only access to resources owned by the subject claim of the token

In-scope merchants

Request

GET /v1/merchants/in-scope?page=0&pageSize=25

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
name query

One or more terms between spaces which will each be matched partially against the name of the merchant

handle query

The unique text 'handle' assigned to the merchant

country query

The country the Merchant resides within

visibility query

Only include merchant listings matching the specified visibility - Visible/Hidden

status query

Only include merchant listings matching the specified status - Active/Pending/Closed

page 0 query

The page parameter (Note: page numbering starts at 0)

pageSize 25 query

The page size parameter (Note: default page size is 25)

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "page": 0, "pageSize": 25, "total": 1, "totalPages": 1, "items": [ { "homeCountry": "NZ", "visibility": "Visible", "status": "Active", "version": 50, "key": "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ", "handle": "widgetinc", "name": "Widgets Inc", "address": "123 Summer Grove", "location": { "latitude": -36.8567852, "longitude": 174.7583516 }, "paymentParameters": { "currency": "USD", "payButtonLabel": "Pay", "limits": { "min": 10.0, "max": 15000.0 }, "paymentPlaceholder": "e.g. 50.00", "mustBePaidInSafari": false }, "referenceDefinitions": [ { "id": 3, "order": 0, "valueType": "Text", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Full Name", "placeholder": "Full Name", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Email", "placeholder": "Email", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Phone", "placeholder": "Phone Number" }, { "id": 123, "order": 0, "valueType": "SingleSelect", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Widget Color", "choices": [ { "label": "Blue", "value": "bl", "order": 0, "isDefault": false }, { "label": "Green", "value": "grn", "order": 0, "isDefault": false }, { "label": "Black", "value": "blk", "order": 0, "isDefault": true } ] } ], "logo": { "android": { "size": 150, "href": "https://pushpay.com/images/merchantlogo/50/123/1" }, "iOS": { "size": 108, "href": "https://pushpay.com/images/merchantlogo/50/123/0" }, "admin": { "size": 80, "href": "https://pushpay.com/images/merchantlogo/50/123/2" }, "account": { "size": 140, "href": "https://pushpay.com/images/merchantlogo/50/123/3" } }, "colors": { "primary": "#cf150a" }, "organizationKey": "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA", "v3OrganizationKey": "df21b3c4e4303167ec70143c8ca1dd78", "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" }, "merchantsettlements": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/settlements" }, "merchantBatches": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/batches" } } } ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchants/in-scope" } } }
<?php
/*
	Example 1
	In-scope merchants
*/
$page = 0;
$pageSize = 25;
$url = "https://api.pushpay.com/v1/merchants/in-scope?page=$page&pageSize=$pageSize";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
// If there is a next page, store the link to it in a variable
if (array_key_exists('next', $jsonResponse['_links'])) {
	$nextLink = $jsonResponse['_links']['next']['href'];
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * In-scope merchants
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		int page = 0;
		int pageSize = 25;
		String urlString = "https://api.pushpay.com/v1/merchants/in-scope?page=" + page + "&pageSize=" + pageSize;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		// Store the link to the next page in a variable
		URL nextLink = response._links.next.href;
		httpConnection.disconnect();
	}

	class Response {
		public int page { get; set; }
		public int pageSize { get; set; }
 		public int total { get; set; }
 		public int totalPages { get; set; }
 		public Response[] items { get; set; }
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
		public Link next;
		public Link prev;
		public Link first;
		public Link last;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# In-scope merchants
set oAuthToken=%1
set page=0
set pageSize=25
set url="https://api.pushpay.com/v1/merchants/in-scope?page=%page%&pageSize=%pageSize%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	In-scope merchants
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var page = 0;
				var pageSize = 25;
				var requestUrl = string.Format("/v1/merchants/in-scope?page={0}&pageSize={1}", page, pageSize);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					var nextLink = response.Links.Next;
					Console.WriteLine(nextLink);
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		public int Page { get; set; }
		public int PageSize { get; set; }
 		public int Total { get; set; }
 		public int TotalPages { get; set; }
 		public Response[] Items { get; set; }
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
		public Link Next { get; set; }
		public Link Prev { get; set; }
		public Link First { get; set; }
		public Link Last { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}

Search Nearby Merchants

GET /v1/merchants/near

Will find merchants near a geolocation (latitude and longitude).

In addition to specifying position, you can also further scope the query to a specific country via the country query parameter.

Valid values for country are:

  • US
  • NZ
  • AU
  • CA

Query string (URL) parameters

Name Type Description
latitude number

Latitude in degrees (valid values for earth are between -90 and +90)

longitude number

Longitude in degrees (valid values for earth are between -180 to +180)

country string

The country the Merchant resides within

page integer

The page parameter (Note: page numbering starts at 0)

pageSize integer

The page size parameter (Note: default page size is 25)

Required Scopes

Scope Description
read Read-only access to resources owned by the subject claim of the token

Search for nearby merchants

Request

GET /v1/merchants/near?country=US&latitude=47.365&longitude=122.1959&page=0&pageSize=25

Headers

Name Value Description
Accept application/hal+json
Authorization Bearer XXXXXXXXX

The bearer token being used to authenticate this request

Parameters

Name Value Type Description
latitude 47.365 query

Latitude in degrees (valid values for earth are between -90 and +90)

longitude 122.1959 query

Longitude in degrees (valid values for earth are between -180 to +180)

country US query

The country the Merchant resides within

page 0 query

The page parameter (Note: page numbering starts at 0)

pageSize 25 query

The page size parameter (Note: default page size is 25)

Response

Status 200 (OK)

Headers

Name Value Description
Content-Type application/hal+json; charset=utf-8

Code Samples

Response

{ "page": 0, "pageSize": 25, "items": [ { "homeCountry": "NZ", "visibility": "Visible", "status": "Active", "version": 50, "key": "MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ", "handle": "widgetinc", "name": "Widgets Inc", "address": "123 Summer Grove", "location": { "latitude": -36.8567852, "longitude": 174.7583516 }, "paymentParameters": { "currency": "USD", "payButtonLabel": "Pay", "limits": { "min": 10.0, "max": 15000.0 }, "paymentPlaceholder": "e.g. 50.00", "mustBePaidInSafari": false }, "referenceDefinitions": [ { "id": 3, "order": 0, "valueType": "Text", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Full Name", "placeholder": "Full Name", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Email", "placeholder": "Email", "maxLength": 100 }, { "id": 4, "order": 0, "valueType": "Email", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Phone", "placeholder": "Phone Number" }, { "id": 123, "order": 0, "valueType": "SingleSelect", "hasChoices": false, "isHidden": false, "isRequired": true, "label": "Widget Color", "choices": [ { "label": "Blue", "value": "bl", "order": 0, "isDefault": false }, { "label": "Green", "value": "grn", "order": 0, "isDefault": false }, { "label": "Black", "value": "blk", "order": 0, "isDefault": true } ] } ], "logo": { "android": { "size": 150, "href": "https://pushpay.com/images/merchantlogo/50/123/1" }, "iOS": { "size": 108, "href": "https://pushpay.com/images/merchantlogo/50/123/0" }, "admin": { "size": 80, "href": "https://pushpay.com/images/merchantlogo/50/123/2" }, "account": { "size": 140, "href": "https://pushpay.com/images/merchantlogo/50/123/3" } }, "colors": { "primary": "#cf150a" }, "organizationKey": "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA", "v3OrganizationKey": "df21b3c4e4303167ec70143c8ca1dd78", "_links": { "self": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ" }, "merchantsettlements": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/settlements" }, "merchantBatches": { "href": "https://api.pushpay.com/v1/merchant/MTIzOkRUclhHb1Jtc24tX3NKMGxjZzJ3cUJqb1ZlTQ/batches" } } } ], "_links": { "self": { "href": "https://api.pushpay.com/v1/merchants/near?country=US&latitude=47.3650&longitude=122.1959" }, "next": { "href": "https://api.pushpay.com/v1/merchants/near?country=US&latitude=47.3650&longitude=122.1959&page=1" } } }
<?php
/*
	Example 1
	Search for nearby merchants
*/
$latitude = 47.365;
$longitude = 122.1959;
$country = 'US';
$page = 0;
$pageSize = 25;
$url = "https://api.pushpay.com/v1/merchants/near?latitude=$latitude&longitude=$longitude&country=$country&page=$page&pageSize=$pageSize";
$oAuthToken = "OAuth TOKEN GOES HERE";

$curl = curl_init($url);
$curlHeaderData = [
	"Accept: application/hal+json",
	"Authorization: Bearer $oAuthToken"
];
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $curlHeaderData);
$jsonResponse = json_decode(curl_exec($curl), true);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($httpCode >= 400) {
    $message = "$httpCode Error";
    if ($jsonResponse['message']) {
        $message = "$message: " . $jsonResponse['message'];
    }
    throw new Exception($message);
}
// If there is a next page, store the link to it in a variable
if (array_key_exists('next', $jsonResponse['_links'])) {
	$nextLink = $jsonResponse['_links']['next']['href'];
}
curl_close($curl);
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Search for nearby merchants
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		double latitude = 47.365;
		double longitude = 122.1959;
		String country = "US";
		int page = 0;
		int pageSize = 25;
		String urlString = "https://api.pushpay.com/v1/merchants/near?latitude=" + latitude + "&longitude=" + longitude + "&country=" + country + "&page=" + page + "&pageSize=" + pageSize;

		HttpURLConnection httpConnection = setUpHttpConnection(new URL(urlString));
		if (httpConnection.getResponseCode() >= 400) {
			System.out.println(httpConnection.getResponseCode() +
				" Error: " + httpConnection.getResponseMessage());
		}
		InputStream inputStream = httpConnection.getInputStream();
		// Store the JSON response as a Java object
		Response response = getJsonResponse(inputStream);
		inputStream.close();
		// Store the link to the next page in a variable
		URL nextLink = response._links.next.href;
		httpConnection.disconnect();
	}

	class Response {
		public int page { get; set; }
		public int pageSize { get; set; }
 		public int total { get; set; }
 		public int totalPages { get; set; }
 		public Response[] items { get; set; }
		// The JSON properties you require should be added here as fields
		public _links _links = new _links();
	}

	class _links {
		public Link self;
		public Link next;
		public Link prev;
		public Link first;
		public Link last;
	}

	class Link {
		public URL href;
	}

	private static Response getJsonResponse(InputStream inputStream) throws IOException {
		BufferedReader streamReader = new BufferedReader(new InputStreamReader(inputStream));
		String jsonString = "";
		while (streamReader.ready()) {
			jsonString += streamReader.readLine();
		}
		return (new Gson()).fromJson(jsonString, Response.class);
	}

	private static HttpURLConnection setUpHttpConnection(URL url) throws IOException {
		String oAuthToken="TOKEN";
		HttpURLConnection httpConnection = (HttpURLConnection) url.openConnection();
		httpConnection.setRequestProperty("Accept", "application/hal+json");
		httpConnection.setRequestProperty("Authorization", "Bearer " + oAuthToken);
		return httpConnection;
	}
}
# Example 1
# Search for nearby merchants
set oAuthToken=%1
set latitude=47.365
set longitude=122.1959
set country="US"
set page=0
set pageSize=25
set url="https://api.pushpay.com/v1/merchants/near?latitude=%latitude%&longitude=%longitude%&country=%country%&page=%page%&pageSize=%pageSize%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace Examples
{
	public class Example1
	{

		/// <summary>
		///	Example 1
		/// </summary>
		/// <remarks>
		///	Search for nearby merchants
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var latitude = 47.365;
				var longitude = 122.1959;
				var country = "US";
				var page = 0;
				var pageSize = 25;
				var requestUrl = string.Format("/v1/merchants/near?latitude={0}&longitude={1}&country={2}&page={3}&pageSize={4}", 
					latitude, longitude, country, page, pageSize);

				client.BaseAddress = new Uri("https://api.pushpay.com");
				client.DefaultRequestHeaders.Accept.Clear();
				client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
				client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", oAuthToken);

				var httpResponse = await client.GetAsync(requestUrl);
				if (httpResponse.IsSuccessStatusCode) {
					var content = await httpResponse.Content.ReadAsStringAsync();
					var response = JsonConvert.DeserializeObject<Response>(
						content, new JsonSerializerSettings {
							ContractResolver = new CamelCasePropertyNamesContractResolver()
					});
					var nextLink = response.Links.Next;
					Console.WriteLine(nextLink);
					return response;
				} else {
					var message = httpResponse.StatusCode + " Error";
					throw new Exception(message);
				}
			}
		}
	}

	public class Response
	{
		public int Page { get; set; }
		public int PageSize { get; set; }
 		public int Total { get; set; }
 		public int TotalPages { get; set; }
 		public Response[] Items { get; set; }
		[JsonProperty(PropertyName = "_links")]
		public Links Links { get; set; }
		// The JSON properties you require should be added here as properties
	}

	public class Links
	{
		public Link Self { get; set; }
		public Link Next { get; set; }
		public Link Prev { get; set; }
		public Link First { get; set; }
		public Link Last { get; set; }
	}

	public class Link {
		public Uri Href { get; set; }
	}
}