Pushpay API

https://pushpay.io/docs
Admin
The Pushpay API provides a flexible and secure REST API and Webhooks for integrating with Pushpay...
Tokens:357,525
Snippets:803
Trust Score:6.1
Update:10 months ago
Show doc for...
Tokens:
Raw
### Get Merchant Batches - Example Request (cURL)

Source: https://pushpay.io/docs/operations/batches

This example demonstrates a GET request to retrieve all batches for a merchant. It includes sample URL parameters for pagination and headers for authentication and content type.

```shell
GET /v1/merchant/MTAxOklkUDVaV0tXNDI4UDRid2FOa0UwOV9ISzRjcw/batches?page=0&pageSize=25

Headers:
Name | Value | Description  
---|---|---
Accept | application/hal+json |   
Authorization | Bearer XXXXXXXXX | The bearer token being used to authenticate this request  
```

--------------------------------

### Get Fund by Key using C#

Source: https://pushpay.io/docs/operations/funds

This C# example demonstrates how to fetch fund details from the Pushpay API using HttpClient. It constructs the request URL, sets authentication headers, and deserializes the JSON response. Ensure you have the Newtonsoft.Json NuGet package installed.

```csharp
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 fund by its key
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var organizationKey = "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA";
				var fundKey = "EC7Aj04kaemLN8XnyuDTnQ";
				var requestUrl = string.Format("/v1/organization/{0}/fund/{1}", organizationKey, fundKey);

				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 Merchant Batches (Example Request)

Source: https://pushpay.io/docs/operations

This example shows a GET request to retrieve all batches for a merchant. It specifies the merchant key and uses query parameters for pagination (page and pageSize). The Authorization header uses a Bearer token.

```http
GET /v1/merchant/MTAxOklkUDVaV0tXNDI4UDRid2FOa0UwOV9ISzRjcw/batches?page=0&pageSize=25

Headers:
Accept: application/hal+json
Authorization: Bearer XXXXXXXXX
```

--------------------------------

### List Open Funds for Organization using C#

Source: https://pushpay.io/docs/operations/funds

This C# code example shows how to asynchronously retrieve a list of open funds for an organization using the Pushpay API. It utilizes HttpClient and Newtonsoft.Json for JSON deserialization. Ensure the necessary NuGet packages are installed.

```csharp
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>
		///	List open funds for organization
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var organizationKey = "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA";
				var requestUrl = string.Format("/v1/organization/{0}/funds", organizationKey);

				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 Single Batch using C#

Source: https://pushpay.io/docs/operations

This C# example demonstrates retrieving a single batch by its key using HttpClient. It configures the request with the necessary headers and authorization, sends a GET request, and deserializes the JSON response. Dependencies include Newtonsoft.Json.

```csharp
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 batch by its key
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTAxOklkUDVaV0tXNDI4UDRid2FOa0UwOV9ISzRjcw";
				var batchKey = "MDp6cmEwMzVOUlV3YmcyUlJhY2RaT1J0VW5hUVE";
				var requestUrl = string.Format("/v1/merchant/{0}/batch/{1}", merchantKey, batchKey);

				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; }
	}
}
```

--------------------------------

### List Organization Funds using C#

Source: https://pushpay.io/docs/operations/funds

This C# example shows how to list all funds for an organization using the HttpClient class. It deserializes the JSON response into a 'Response' object. Ensure the Newtonsoft.Json NuGet package is installed.

```csharp
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>
		///	List all funds for organization
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var organizationKey = "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA";
				var fundStatus = "All";
				var requestUrl = string.Format("/v1/organization/{0}/funds?fundStatus={1}", organizationKey, 
					fundStatus);

				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; }
	}
}
```

--------------------------------

### List Funds for a Merchant - Java Example

Source: https://pushpay.io/docs/operations/funds

This Java example shows how to retrieve a list of funds for a merchant via the Pushpay API. It uses `HttpURLConnection` to make a GET request and `Gson` library to parse the JSON response. Error handling for HTTP status codes is included.

```java
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 2
 * List funds for a merchant listing that does not have a default fund
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

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

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

```

--------------------------------

### Retrieve Settlement Payments in C#

Source: https://pushpay.io/docs/operations/settlements

This C# example shows how to fetch settlement payments using `HttpClient` and Newtonsoft.Json. It sets up the `HttpClient` with the base API address and includes default headers for `Accept` and `Authorization`. The code constructs the request URL with settlement details and pagination, sends a GET request, and deserializes the JSON response into a `Response` object, handling potential HTTP errors.

```csharp
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 the payments associated with a settlement, only the page parameter is supported
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var settlementKey = "MTI0MzpWMXVLQmV4VzVqa1FKY3ZiOVJVOFBRUGUtQU0";
				var page = 0;
				var pageSize = 25;
				var requestUrl = string.Format("/v1/settlement/{0}/payments?page={1}&pageSize={2}", settlementKey, 
					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; }
	}
}
```

--------------------------------

### Java HTTP Request Setup

Source: https://pushpay.io/docs/operations/settlements

This Java snippet sets up the necessary imports for making HTTP requests and handling JSON responses using Google's Gson library. It includes classes for interacting with URLs, managing connections, and parsing data, which are foundational for building API clients.

```java
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

```

--------------------------------

### Get Fund by Key using Java

Source: https://pushpay.io/docs/operations/funds

This Java example demonstrates how to fetch fund information from the Pushpay API. It utilizes HttpURLConnection for making the GET request and Gson for JSON parsing. The code includes setup for authentication and error handling based on HTTP response codes.

```Java
import com.google.gson.Gson;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.*;

/**
 * Example 1
 * Get fund by its key
 *
 * This example uses the Gson library to parse JSON
 */

public class Example {

	public static void main(String[] args) throws IOException {
		String organizationKey = "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA";
		String fundKey = "EC7Aj04kaemLN8XnyuDTnQ";
		String urlString = "https://api.pushpay.com/v1/organization/" + organizationKey + "/fund/" + fundKey;

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

```

--------------------------------

### Pagination Links Example

Source: https://pushpay.io/docs/guidance/organizations

An example of pagination links found in API responses, showing the 'self' and 'next' links for navigating through paged results.

```JSON
{
    "_links": {
            "self": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=1"
            },
            "next": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=2"
                }
            }


```

--------------------------------

### Sample Merchant Listing Data

Source: https://pushpay.io/docs/guidance/payments_synchronization

An example JSON response structure for merchant listings, including key identifiers like 'key' and 'handle', along with other relevant details such as 'name' and 'address'.

```json
{
  "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
      }
    }
  ]
}
```

--------------------------------

### API Error Example: Invalid Order By Column

Source: https://pushpay.io/docs/operations/settlements

This example illustrates an API request that is expected to fail due to an invalid 'orderBy' column. It shows the GET request path and headers that would be sent, highlighting the specific parameter causing the error.

```http
GET /v1/merchant/MTIzNDphSXNSSE1DWDhMTUh4dkpDQmllcUpIR2FpX28/settlements?orderBy=settlementDate DESC&page=0&pageSize=25 HTTP/1.1
Host: api.pushpay.com
Accept: application/hal+json
Authorization: Bearer XXXXXXXXX
```

--------------------------------

### Constructing a Basic Pushpay Giving Link URL

Source: https://pushpay.io/docs/guidance/preconfigured_giving_link

This example demonstrates the fundamental structure of a Pushpay Preconfigured Giving Link. It combines the base URL with a merchant listing handle and optional parameters, separated by '?' and '&'. Ensure parameters are URL-encoded if they contain special characters.

```text
https://pushpay.com/g/merchantlistinghandle?a=10&fnd=tithes&al=true&fndv=lock&rcv=false&r=monthly&rsd=2019-10-12&ret=date&red=2019-11-11&reo=4&f[0]=ReferenceFieldName&ufn=FirstName&uln=LastName&ue=email@domain.com&up=%2B15417543010&sr=fm12345&nt=This%20is%20a%20note&ad=%7B%22name%22%3A%22some%20name%22%7D&ru=Brand%20New%20Redirect
```

--------------------------------

### Settlement Response Example

Source: https://pushpay.io/docs/guidance/organizations

An example JSON structure for a settlement, including its key, name, total amount, type, payment count, estimated deposit date, reconciliation status, and links to related resources.

```JSON
{
        "key": "MDpkQUFOQ1FzdE1BLVZfVWZFdEZkQ3dvb3YyTDg",
        "name": "Settlement #1",
        "totalAmount": {
        "amount": "202.00",
        "currency": "USD"
        },
        "type": "ACH",
        "totalPayments": 2,
        "estimatedDepositDate": "2016-01-03T07:00:00Z",
        "isReconciled": true,
        "_links": {
        "self": {
            "href": "https://api.pushpay.com/v1/settlement/MDpkQUFOQ1FzdE1BLVZfVWZFdEZkQ3dvb3YyTDg"
        },
        "settlementpayments": {
            "href": "https://api.pushpay.com/v1/settlement/MDpkQUFOQ1FzdE1BLVZfVWZFdEZkQ3dvb3YyTDg/payments"
        }
        }
}

```

--------------------------------

### Close Fund - C# Example

Source: https://pushpay.io/docs/operations/funds

This C# code example shows how to close a fund with active payment schedules using HttpClient. It constructs a PATCH request to the Pushpay API, serializes the request body to JSON, and handles the API response. Ensure you have the Newtonsoft.Json NuGet package installed.

```csharp
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 Example2
	{

		/// <summary>
		///	Example 2
		/// </summary>
		/// <remarks>
		///	Close fund with active payment schedules
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var organizationKey = "MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA";
				var fundKey = "EC7Aj04kaemLN8XnyuDTnQ";
				var requestUrl = string.Format("/v1/organization/{0}/fund/{1}", organizationKey, fundKey);

				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 {
					  status = "Closed"
					});
				var body = new StringContent(jsonString, Encoding.UTF8, "application/json");
				var requestMessage = new HttpRequestMessage(new HttpMethod("PATCH"), 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; }
	}
}
```

--------------------------------

### Pagination Links Example

Source: https://pushpay.io/docs/api

An example of the '_links' object within a paginated response, showing links for 'self', 'next', 'pref', 'first', and 'last' pages. This enables programmatic navigation through result sets.

```json
{
    "items": [
        ....
    ],
    "page": 2,
    "pageSize": 25,
    "total": 120,
    "totalPages": 5,
    "_links": {
        "self": {
            "href": "https://api.pushpay.com/v1/merchants?country=US&page=2"
        },
        "next": {
            "href": "https://api.pushpay.com/v1/merchants?country=US&page=3"
        },
        "pref": {
            "href": "https://api.pushpay.com/v1/merchants?country=US&page=1"
        },
        "first": {
            "href": "https://api.pushpay.com/v1/merchants?country=US&page=0"
        },
        "last": {
            "href": "https://api.pushpay.com/v1/merchants?country=US&page=4"
        }
    }
}
```

--------------------------------

### Get User Claims via c# HttpClient

Source: https://pushpay.io/docs/operations/diagnostics

Retrieves details about the authenticated user's claims by making a GET request to the /v1/diagnostics/identity endpoint using C# HttpClient. This method requires an OAuth token for authentication and deserializes the JSON response into a `Response` object. Ensure the Newtonsoft.Json NuGet package is installed.

```csharp
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>
		///	Returns details about the authenticated users claims
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var requestUrl = "/v1/diagnostics/identity";

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

```

--------------------------------

### Pagination Links Example

Source: https://pushpay.io/docs/guidance/batches

An example of the '_links' object within a paginated API response, demonstrating 'self' and 'next' links. The 'next' link provides the URL for retrieving the subsequent page of results.

```JSON
    "_links": {
            "self": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=1"
            },
            "next": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=2"
                }
            }

```

--------------------------------

### GET /v1/organization/{organizationKey}/campuses

Source: https://pushpay.io/docs/operations/organizations

This endpoint retrieves a list of campuses for a specific organization. The example demonstrates handling a non-existent organization, which results in an error response.

```APIDOC
## GET /v1/organization/{organizationKey}/campuses

### Description
Retrieves details of organization campuses. This example specifically shows the request for a non-existent organization key.

### Method
GET

### Endpoint
`https://api.pushpay.com/v1/organization/{organizationKey}/campuses`

### Parameters
#### Path Parameters
- **organizationKey** (string) - Required - The unique identifier for the organization.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
```bash
# Example using curl
curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer <YOUR_OAUTH_TOKEN>" "https://api.pushpay.com/v1/organization/MTIzOi1Yb1ByLWxtakFoMVdEaUlrWFpIdnhfODd0NA/campuses"
```

### Response
#### Success Response (200)
- **_links** (object) - Contains links related to the response, including a self link.
  - **self** (object) - Link to the current resource.
    - **href** (string) - The URL of the self link.

#### Error Response (e.g., 404 Not Found)
- **message** (string) - Description of the error, e.g., "Organization does not exist".

#### Response Example (Error)
```json
{
  "message": "Organization does not exist"
}
```
```

--------------------------------

### Get Organization Settlements (cURL)

Source: https://pushpay.io/docs/operations/settlements

Example cURL request to retrieve settlements for a specific organization. It demonstrates the use of query parameters like 'page' and 'pageSize' and includes necessary headers for authentication and content negotiation.

```bash
GET /v1/organization/MTIzNDo0WmwxbFo2NjV2SXpBS1VSOTFlTmhtSDlYY1k/settlements?page=0&pageSize=25
#### Headers
Name | Value | Description  
---|---|---  
Accept | application/hal+json |   
Authorization | Bearer XXXXXXXXX | The bearer token being used to authenticate this request  
```

--------------------------------

### Example JSON Response for Organization Merchant Listings

Source: https://pushpay.io/docs/guidance/meta

An example JSON structure representing a list of organizations, including details like home country, visibility, status, version, key, handle, name, and address. This data is returned when querying for organizations.

```JSON
{
"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
},

}
```

--------------------------------

### Retrieve Settlements with Invalid OrderBy (cURL)

Source: https://pushpay.io/docs/operations/settlements

Demonstrates making a GET request to retrieve settlements using an invalid orderBy parameter. This example highlights how the API responds to incorrect sorting configurations. It requires an OAuth token for authentication.

```bash
set oAuthToken=%1
set merchantKey="MTIzNDphSXNSSE1DWDhMTUh4dkpDQmllcUpIR2FpX28"
set orderBy="settlementDate DESC"
set page=0
set pageSize=25
set url="https://api.pushpay.com/v1/merchant/%merchantKey%/settlements?orderBy=%orderBy%&page=%page%&pageSize=%pageSize%"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer %oAuthToken%" %url%
```

--------------------------------

### Sample Organization Merchant Listing Data

Source: https://pushpay.io/docs/guidance/diagnostics

Example JSON response for retrieving organization merchant listings. It includes details like home country, visibility, status, version, key, handle, name, and address. The 'key' and 'handle' are important for subsequent API calls and integration.

```json
{
"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

}

```
```

--------------------------------

### List Funds Visible on a Merchant (PHP)

Source: https://pushpay.io/docs/operations/funds

Example PHP code to make a GET request to the Funds API to list funds for a merchant. This assumes you have a valid bearer token and merchant key.

```PHP
<?php

$merchantKey = 'MTAxOklkUDVaV0tXNDI4UDRid2FOa0UwOV9ISzRjcw';
$bearerToken = 'Bearer XXXXXXXXX'; // Replace with your actual token

$url = "https://api.pushpay.io/v1/merchant/{$merchantKey}/funds";

$headers = [
    'Accept: application/hal+json',
    "Authorization: {$bearerToken}"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
} else {
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    echo "HTTP Status Code: " . $httpCode . "\n";
    echo "Response Body:\n";
    echo $response;
}

curl_close($ch);

?>

```

--------------------------------

### Example Organization Merchant Listing JSON Response (JSON)

Source: https://pushpay.io/docs/guidance/organizations

An example JSON structure representing a merchant listing. It includes fields like 'key' for unique identification, 'handle' for Pre-configured Giving links, and other details such as 'name' and 'address'. This data is used to store reference information.

```JSON
{
"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

}

}
]

}
```

--------------------------------

### Pagination Links Example

Source: https://pushpay.io/docs/guidance/meta

Example of pagination links returned in an API response. The '_links' object contains 'self' and 'next' properties, with 'href' attributes pointing to the current and next pages of results, respectively.

```json
    "_links": {
            "self": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=1"
            },
            "next": {
            "href": "https://api.pushpay.com/v1/merchant/MTpZc2M4M3hOM05KMmdxOHpDQklvYkxqQWpfY2M/settlements?updatedFrom=2015-12-11T00:00:00Z&page=2"
                }
            }
```

--------------------------------

### List Funds for Merchant (C#)

Source: https://pushpay.io/docs/operations/funds

This C# example shows how to list funds for a merchant using the HttpClient. It handles authentication with a Bearer token and deserializes the JSON response.

```csharp
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>
		///	List funds for a merchant listing that does not have a default fund
		/// </remarks>
		public async Task<Response> Example(string oAuthToken)
		{
			using (var client = new HttpClient()) {
				var merchantKey = "MTAxOklkUDVaV0tXNDI4UDRid2FOa0UwOV9ISzRjcw";
				var requestUrl = string.Format("/v1/merchant/{0}/funds", 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; }
	}
}
```

--------------------------------

### Search Organizations (cURL)

Source: https://pushpay.io/docs/operations/organizations

This cURL example demonstrates how to search for organizations using the Pushpay API. It shows a GET request to the /v1/organizations endpoint with optional query parameters for name and status. The request includes Accept and Authorization headers.

```shell
curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer XXXXXXXXX" "https://api.pushpay.com/v1/organizations?page=0&pageSize=25"
```

--------------------------------

### cURL: Retrieve Settlements with Filters

Source: https://pushpay.io/docs/operations/settlements

This example uses cURL to make a GET request to the Pushpay API to retrieve settlements based on specified filters. It includes setting the OAuth token, merchant key, and various query parameters like orderBy, isReconciled, name, type, page, and pageSize.

```shell
#!/bin/bash
oAuthToken="YOUR_TOKEN"
merchantKey="YOUR_MERCHANT_KEY"
orderBy="transactions ASC"
isReconciled=True
name="settlementName"
type="ACH"
page=0
pageSize=25
url="https://api.pushpay.com/v1/merchant/${merchantKey}/settlements?orderBy=${orderBy}&isReconciled=${isReconciled}&name=${name}&type=${type}&page=${page}&pageSize=${pageSize}"

curl -i -H "Accept: application/hal+json" -H "Authorization: Bearer ${oAuthToken}" "${url}"
```
Tokens:
Raw