NAV
shell python ruby php javascript csharp

Introduction

Copy to Clipboard
# Live API url https://api.placepay.com/
Copy to Clipboard
# Test API url https://test-api.placepay.com/

The PlacePay integration API is based on a RESTful API design with some nuances. You can explore the API implementation specifics in the general section.

Installation

Use one of our premade libraries for Python, Ruby, PHP, Node, or .NET (Beta).

Testing

There is a safe and full-featured test application available at test-api.placepay.com. All test api keys will be start with "test_private_key" or "test_public_key".

Use the test api to build and test your integration without initiating any live payments or email notices. The pre-built libraries for Python, Ruby, PHP, Node, or .NET (Beta) will automatically adjust to the test API when using a test API key.


General

The HTTP verbs used are GET to select objects, POST to create objects, PUT to update objects, and DELETE to delete objects. Objects can be manipulated in single, bulk, or query modes.

Authentication

Copy to Clipboard
# Using curl, you can pass the API key with each request # Make sure to append your API key with `:` when using `curl`. curl "https://api.placepay.com/transactions" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

PlacePay uses API keys for accessing the API. Your API keys can be found on your settings page under API Keys.

PlacePay expects for the API key to be included in all API requests to the server using HTTP Basic Auth.

Methods

Select

Select method uses the HTTP verb GET to retrieve objects and works in two modes: single and query.

Copy to Clipboard
# Single mode curl "https://api.placepay.com/transactions/gkXzxwqyMw7LWAIFJecc4I90" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

Single mode

GET https://api.placepay.com/transactions/{id1}[,{id2},...]

No request body


Copy to Clipboard
# Query mode curl "https://api.placepay.com/transactions/?type=refund" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

Query mode (See the query language)

GET https://api.placepay.com/transactions/?field=value

No request body

Create

Create method uses the HTTP verb POST to create objects and works in two modes: single and bulk.

Copy to Clipboard
# Single mode curl "https://api.placepay.com/accounts/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d email="joe.chip@example.com" \ -d full_name="Joe Chip" \ -d user_type="payer"

Single mode

POST https://api.placepay.com/accounts/

Request body:

{ ... } single json object


Copy to Clipboard
# Bulk mode curl "https://api.placepay.com/accounts/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d [0]email="joe.chip@example.com" \ -d [0]full_name="Joe Chip" \ -d [0]user_type="payer" \ -d [1]email="glen.runciter@example.com" \ -d [1]full_name="Glen Runciter" \ -d [1]user_type="payer"

Bulk mode

POST https://api.placepay.com/accounts/

Request body:

[ { ... }, { ... }, { ... } ] Array with multiple objects


Update

Update method uses the HTTP verb PUT to update objects and works in three modes: single, query, and bulk.

Copy to Clipboard
# Single mode curl "https://api.placepay.com/accounts/rqlPhhU3aJ8DWBF5zPJI8HrU" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d email="joe.chip@example.com"

Single mode

PUT https://api.placepay.com/accounts/{id1}[,{id2},...]

{ ... } single json object


Copy to Clipboard
# Query mode curl "https://api.placepay.com/accounts/?email=joe.chip@example.com&query_mode=1" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d email="joe.chip@example.com"

Query mode (See the query language)

PUT https://api.placepay.com/accounts/?field=value

{ ... } single json object with fields to update


Copy to Clipboard
# Bulk mode curl "https://api.placepay.com/accounts/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d [0][id]="rqlPhhU3aJ8DWBF5zPJI8HrU" \ -d [0][email]="joe.chip@example.com" \ -d [1][id]="kswxX5hFW57SN7icmdcaszd4" \ -d [1][email]="glen.runciter@example.com"

Bulk mode

PUT https://api.placepay.com/accounts/

[ { id: {id1}, ... }, { id: {id2}, ... } ] Array with multiple objects


Delete

Delete method uses the HTTP verb DELETE to delete objects and works in three modes: single, query, and bulk.

Copy to Clipboard
# Single mode curl "https://api.placepay.com/invoices/kswxX5hFW57SN7icmdcaszd4" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X DELETE

Single mode

PUT https://api.placepay.com/invoices/{id1}[,{id2},...]

No request body


Copy to Clipboard
# Query mode curl "https://api.placepay.com/invoices/?reference_id=example@example.com&query_mode=1" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X DELETE

Query mode (See the query language)

PUT https://api.placepay.com/invoices/?field=value

No request body


Copy to Clipboard
# Bulk mode curl "https://api.placepay.com/invoices/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X DELETE \ -d [0][id]="rqlPhhU3aJ8DWBF5zPJI8HrU" \ -d [1][id]="kswxX5hFW57SN7icmdcaszd4"

Bulk mode

PUT https://api.placepay.com/invoices/

[ { id: {id1}, ... }, { id: {id2}, ... } ] Array with multiple objects

Embedded objects

Resource objects can have other related resource objects embedded within their object hierarchy. This means that a top- or higher-level resource will return the main resource object along with the underlying embedded object hierarchy.

Copy to Clipboard
# Single mode curl "https://api.placepay.com/invoices/lEOCGQRFHXtZg51uBGHpyd7h" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
Copy to Clipboard
{ "id": "16mgrY95eKG6oZ1hDx3kmBOkB", "object": "invoice", "accepted_payment_state": "full", "amount": 1000, "description": "September Rent", "due_date": "2015-09-01", "type": "rent", "items": [{ "id": "rqlPhhU3aJ8DWBF5zPJI8HrU", "object": "invoice_item", "amount": 100, "amount_allocated": 100, "date_incurred": "2017-12-10 20:41:40", "description": "Wolf Chow", "invoice_id": "16mgrY95eKG6oZ1hDx3kmBOkB", "prorated": true, "recurring": false, "type": "pet_food", "allocations": [{ "id": 285, "object": "invoice_item_allocation", "amount": 100, "item_id": "rqlPhhU3aJ8DWBF5zPJI8HrU", "payer_id": "1GNFiZvNHINWhoVEWAMqjw0uo", "type": "auto" }] }], "payers": [{ "id": "1GNFiZvNHINWhoVEWAMqjw0uo", "object": "invoice_payer", "access": true, "account_id": "LVWc2lnL0R6MmGgzVmIzzKmo", "active": true, "amount_allocated": 1000, "amount_paid": 1000, "email": "joe.chip@example.com", "first_name": "Joe", "invoice_id": "16mgrY95eKG6oZ1hDx3kmBOkB", "last_name": "Chip", "last_payment_date": "2015-08-28", "paid": true, "payments": [{ "id": "258V5IKHHoYxr0qyeesqkgPgY", "object": "transaction", "account_id": "LVWc2lnL0R6MmGgzVmIzzKmo", "amount": 100.83, "deposit_account_id": "W3flrWSs1kzSCYytR3XIwjb3", "description": "string", "failed_timestamp": "2017-12-10 20:41:40", "fee": 1.95, "initiated_timestamp": "2017-12-10 20:41:40", "payment_method": {}, "payment_method_id": "19QsDurdSxJ0gVNzOcQSlew3D", "settled": true, "status": "complete", "status_details": "string", "type": "charge" }], "payments_transfer_date": "2015-09-04", "payments_transfered": true }], "fee_settings": {} }

For example, the /invoices endpoint has a list of associated /invoice_items embedded within its hierarchy. As you can see from the example, the associated item object is returned in the embedded items object list of the invoice.

Embedded objects can also be accessed directly using the embedded object resource URL. For example, https://api.placepay.com/invoices/Ca2BJALtdq9V76zfCpe90YJf/items.

If you create or update an object containing embedded objects, then the embedded objects will be created, updated, or deleted, respectively.


Query language

Conditionals

Copy to Clipboard
# Example of using the `greater-than` operator curl "https://api.placepay.com/transactions/?initiated_timestamp=>2017-11-01" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
Copy to Clipboard
# Example of combining the `greater-than`, `less-than`, and `and` operator curl "https://api.placepay.com/transactions/?initiated_timestamp=>2017-11-01&initiated_timestamp=<2017-11-15" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
Copy to Clipboard
# Example of using the `greater-than` operator curl "https://api.placepay.com/transactions/?status=declined|canceled" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
Operator Example
= ?field=value
< ?field=<value
<= ?field=<=value
> ?field=>value
>= ?field=>=value
! ?field=!value
or ?field=<value1|>value2
& ?field=>=value&field=<=value
match ?field=?val*

Subobject query

?object[field]=value

Special fields

Copy to Clipboard
# Example of using the special range fields curl "https://api.placepay.com/transactions/?limit=5&offset=100" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
Name Example
fields ?fields[0]=*&fields[1]=hidden_field
limit ?limit=10
offset ?offset=10
order_by ?order_by=initiated_timestamp
group_by ?group_by=status

Fields Preference

You can modify what fields are returned by setting the fields parameter. Also, not all fields are returned by default. You can specify hidden fields using the fields parameter as well. If you're using one of the libraries, you can set your fields preference globally using the default_param class method.

Custom Fields

Copy to Clipboard
curl "https://api.placepay.com/transactions/3axWdCgzecx9HR7PSOqP2" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT -d "custom_fields[custom]=data"
Copy to Clipboard
{ "id": "HWIjDMdcZHl2Dj1i6lNXW4r5", "object": "transaction", "account_id": "r3jyJXI3bpLs9m9YZV6OiFib", "amount": 177.4, "deposit_account_id": "129BOlWKt2Ta52bU99hKZkH3C", "description": "string", "failed_timestamp": null, "fee": 1.95, "initiated_timestamp": "2018-05-10 12:32:18", "payment_method_id": "10f10tnMIIzFZkj7RDQvcCmVg", "status": "complete", "status_details": "string", "type": "charge", "custom_fields": { "custom": "data" } }

Custom fields can be added to any object for reference. Fields can be added or updated independently. To delete a custom field just update its value to null.


Errors

Single object response

Copy to Clipboard
{ "object": "error", "error_type": "InvalidArguments", "error_description": "secret_key", "details": { "secret_key": "Must be at least 7 characters and contain at least one number and one letter." } }

Bulk object response

Copy to Clipboard
{ "object": "error", "error_type": "InvalidArguments", "error_description": "[0][accepted_terms], [0][email], [0][secret_key], [1][email], [1][accepted_terms], [1][secret_key]", "details": { "object": "list", "values": [ { "secret_key": "Must be at least 7 characters and contain at least one number and one letter.", "accepted_terms": "Must be a valid bool", "email": "Must be a valid email" }, { "secret_key": "Must be at least 7 characters and contain at least one number and one letter.", "email": "Must be a valid email", "accepted_terms": "Must be a valid bool" } ] } }

Errors are relayed via the HTTP Status Code, with additional information included in the response body.

The PlacePay API uses the following error codes:

Code Meaning
400 Bad Request -- This error is relayed when the request cannot be completed due to a general error, or invalid or missing parameters. In the case of invalid parameters, then the response body’s error type will be InvalidArguments, and the response object will contain a list of invalid parameters along with a short description.
401 Unauthorized -- This error is relayed when the request is not authorized to perform the desired action. This is usually due to an expired or invalid access_token (i.e., API key).
403 Forbidden -- This error is relayed when the request has a valid access_token, but that access_token does not have the necessary privileges to perform the desired action.
404 Not Found -- The specified object or resource could not be found. This is caused by requesting an object by id that either no longer exists, or is not in the scope of the API key's access view.
405 Method Not Allowed -- This error is relayed when the requested resource exists, but the requested method (e.g., POST) is not allowed to be performed on that resource.
429 Too Many Requests -- This error is relayed when too many requests have been made too frequently, generally due to overuse of a specific resource.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Aggregate functions

Copy to Clipboard
curl "https://api.placepay.com/transactions/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "initiated_timestamp=>2018-05-01" \ -d "fields=sum(amount),status" \ -d "group_by=status"
Copy to Clipboard
[ { "status": "complete", "sum(amount)": 40000 }, { "status": "declined", "sum(amount)": 5000 } ]

The following aggregate functions are supported:

sum | count | avg | min | max

To utilize aggregate functions, you can specify the function and desired field(s) via the fields parameter. Aggregate functions can be combined with the group_by special parameter as well.


Timezone

The default timezone for any date objects can be customized for any user. By default, date objects are perceived as US/Eastern but this can be adjusted to any timezone or set to UTC.


Pay Plugin

Copy to Clipboard
<form action="/path/to/your/post/method" method="POST"> <script src="https://placepay.com/plugins/pay.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-amount="1000.00" data-description="First Month's Rent"> </script> </form>

If you want your customers to be able to pay from within your own portal or platform, you can use the fully responsive Pay plugin. This will embed a Pay button into your form that will open a payment confirmation modal to allow your customer to enter/reuse their payment method(s), confirm, and pay.

Once a payment is confirmed, the Pay plugin will add a hidden rs_transaction_id form element and automatically submit the form.

On the server side, you can validate the rs_transaction_id using the transactions api.

Copy to Clipboard
rs_transaction_id = '19QsDurdSxJ0gVNzOcQSlew3D' curl "https://api.placepay.com/transactions/$rs_transaction_id" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d status=complete

For a more seamless experience, you can create persistent payer accounts, which will allow customers to access their stored payment methods across all devices.


Example

Copy to Clipboard
<form action="/path/to/your/post/method" method="POST"> <script src="https://placepay.com/plugins/pay.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-access-token="${access_token}" data-amount="1000.00" data-description="Example Payment"> </script> </form>

Open Pay Plugin via Pay Now Button

Below is an example of the pay plugin. You can click the Pay Now button to see an example of the modal.


Open Pay Plugin via JavaScript

Copy to Clipboard
<script src="https://placepay.com/plugins/pay.js"></script> <script> Place.pay.open({ key: "public_key_AWcpDnNBB7oLfNqfQ6g66262", access_token: "${access_token}", amount: 1000.0, description: "Example Payment", on: { autopay_changed: function (data) { // handle callback } } }) </script>

You can also launch the plugin from javascript instead of using the embedded html button by calling Place.pay.open(), as seen in the example.

To replicate the automatic form submission functionality of the Pay Now button, you can pass the desired html form element in the open call using the bind_to_form parameter.


Embed the Pay Plugin Directly on Page

Copy to Clipboard
<script src="https://placepay.com/plugins/pay.js"></script> <script> Place.pay.open({ key: "public_key_AWcpDnNBB7oLfNqfQ6g66262", access_token: "${access_token}", amount: 1000.0, description: "Example Payment", embed: true, embed_container: $('#payment-form').get(0), on: { autopay_changed: function (data) { // handle callback } } }) </script>

The standard plugin is launched as a modal but you can embed the pay plugin directly on the page by setting the embed attribute to true.

If you're using the javascript interface, you can pass an embed_container attribute to specify what html element on the page will contain the plugin.

If the embed_container is or resides within a form, upon completion of a payment, the form will be automatically submitted. You can pass a desired html form element in the open call using the bind_to_form parameter as well.


Persistent Accounts

Persistent accounts allow customers to access their stored payment methods across all devices for a more seamless experience.

Copy to Clipboard
# Create a payer account curl "https://api.placepay.com/accounts/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d email="joe.chip@example.com" \ -d full_name="Joe Chip" \ -d user_type="payer"

Create an account

First, you need to create a payer account with the customer's email and name.

Once an account has been created, you'll need to store the account['id'] of the resulting PlacePay account.


Creating a session access token for the Pay plugin

Copy to Clipboard
# Create an access token account_id = '20pt57fgkN2V5G8GYsch7vrHR' curl "https://api.placepay.com/accounts/$account_id/access_tokens" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d type=session_access

To load the Pay plugin with a customer's persistent account, you need to create a unique access-token for your customer. For access to the plugin, the new access-token must be a "session_access" type token, and it must be created with the account id of the customer. You'll need to create a new access-token every time a new Pay button is loaded.


Launching the Pay plugin

Copy to Clipboard
<!-- Then when you render the plugin, pass the access token. Note: the access_token only works once --> <form action="/path/to/your/post/method" method="POST"> <script src="https://placepay.com/plugins/pay.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-amount="1000.00" data-description="First Month's Rent" data-access-token="${access_token}"> </script> </form>

Once you've created a new access-token, you can pass it to the Pay plugin using the data-access-token parameter. Once your customer clicks the button, their persistent account will load with any of their stored payment methods or settings.


Simplified Account Management With Usernames

Copy to Clipboard
# Create a payer account curl "https://api.placepay.com/accounts/?fields=*,username,access_tokens" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d email="joe.chip@example.com" \ -d full_name="Joe Chip" \ -d user_type="payer" \ -d access_tokens[0][type]='session_access'

For a simpler way to manage accounts without needing to store the corresponding account id, you can utilize the unique username field to create or update an existing account, and create a new session_access token in one API request.


Autopay

If you are using the Pay plugin with the autopay option, you can access the list of payers who enroll using the plugin via the API, and with that list create a task or trigger to automatically initiate any payments due automatically.

Example button

Copy to Clipboard
<!-- Then when you render the plugin, pass the access token. Note: the access_token only works once --> <script src="https://placepay.com/plugins/pay.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-access-token="${access_token}" data-autopay-only="true"> </script>


Get Current Enrollments

Copy to Clipboard
curl "https://api.placepay.com/autopay_enrollments" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

First, pull a list of all enrollments using the API through the /autopay_enrollments endpoint. This will return a list of all payers who enrolled in automatic payments.


Create Payment Objects

Second, create a list of payments due to those who've enrolled. You can only use the payment_method_id that is defined in each enrollment; otherwise the payment will be rejected.


Process Automatic Payments

Copy to Clipboard
curl "https://api.placepay.com/transactions/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "[0][type]=charge" \ -d "[0][amount]=1000" \ -d "[0][description]=March Rent" \ -d "[0][payment_method_id]=$payment_method_id" \ -d "[0][deposit_account_id]=$deposit_account_id"

Last, initiate the payments using the /transactions endpoint by posting the payment objects created in the last step. The resulting object list will contain a list of completed or declined payments in the same order as the original payment object list created in the last step.


Javascript Callbacks

Copy to Clipboard
<script> Place.pay.on( '.mybutton', 'loaded', function() { console.log('event captured') }) </script>
Copy to Clipboard
<script> Place.pay.on( '.mybutton', 'autopay_changed', function( evt ) { if ( evt.autopay ) console.log('autopay enabled') else console.log('autopay disabled') }) </script>

If you want to watch for a response from the plugin to see if a certain event was triggered, then there are serveral available callbacks: processing, paid, declined, canceled, autopay_changed, closed, loaded, and error

Loaded

The loaded callback is triggered every time the user opens the Pay plugin popup.

Processing

The processing callback is triggered every time the user starts the payment process. This callback is followed by any of paid, canceled, or declined callbacks.

The paid callback is triggered after a payment has been successfully processed. If this is automatically triggering a form request, no close event will follow.

Event Data Description
transaction_id The transaction id of the completed payment
payments_attempted The number of payment attempts made

Declined

The declined callback is triggered every time an initiated payment is declined. To make a test declined request on the test server, you can use the card number 5555-5555-5555-4444.

Event Data Description
declined_message The declined reason message

Canceled

The canceled callback is triggered if the payment confirmation is canceled by the user.

Autopay Changed

The autopay_changed callback is triggered if the autopay enrollment state is changed by the user.

Event Data Description
autopay The enrollment details. If null, the user has unenrolled

Closed

The closed callback is triggered if the user closes the Pay plugin window for any reason, or a successful payment has been made. Note, if this is automatically triggering a form request, no close event will follow a successful payment.

Event Data Description
transaction_id Only present after a successful payment. The transaction id of the completed payment
payments_attempted The number of payment attempts made

Error

The error callback is triggered if an unexpected issue occurs within the plugin.

Event Data Description
error_code The error code

Locking the plugin

Copy to Clipboard
<script> Place.pay.on( '.mybutton', 'autopay_changed', function( evt ) { Place.pay.lock() $.post('/autopay_flag', { enabled: !!evt.autopay }, function() { Place.pay.unlock() }) }) </script>

If you're making an asynchronous request triggered by a javascript callback, it's recommended to lock the plugin while processing. This will ensure there are no interruptible actions taken by the user.


Custom Fields

Copy to Clipboard
<script src="https://placepay.com/plugins/pay.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-access-token="${access_token}" data-amount="1000" data-description="Rent" data-custom-fields="${uri_encode({'custom':'example'})}"> </script>

Custom fields can be passed to the Pay plugin and will be added to any transaction object for reference.


Plugin Configuration

Script Tag Attributes

Parameter Description
data-key
required
Your public API key.
data-amount
optional with invoice id
The amount of the payment.
data-amount-editable Boolean to control modification of amount via input field.
data-amount-min Minimum payment amount accepted for transaction.
Default: 0.01
data-amount-max Maximum payment amount accepted for transaction.
Default: 500000.00
data-description
required
The description of the payment.
data-deposit-account-id Specify the recipient's deposit account id of the payment. Not required for accounts with only one deposit account.
data-access-token Load an existing payer's account settings. See the persistent accounts section for more information.
data-invoice-id If utilizing the invoice api, pass the desired invoice id.
data-order-number Provide an order number to use as a reference for the transaction.
data-recurring-invoice-id If utilizing the recurring invoice API and autopay, pass the desired recurring invoice id.
data-cards Use true or false to specify whether card payments are allowed. Default is true.
data-ach Use true or false to specify whether ACH payments are allowed. Default is true.
data-email The payer's email address, if available.
data-full-name The payer's full name, if available.
data-autopay Use true or false to specify whether autopay is allowed. Default is false.
data-custom-fields Transaction custom fields JSON object. *Example: data-custom-fields='{"example":"data"}'
data-btn-class Custom CSS class for the pay button.
data-btn-text Custom text for the pay button.
data-embed If true, embeds the plugin directly on the page.

Javascript Interface Attributes

Parameter Description
key
required
Your public API key.
amount
optional with invoice id
The amount of the payment.
amount_editable Boolean to control modification of amount via input field.
amount_min Minimum payment amount accepted for transaction.
Default: 0.01
amount_max Maximum payment amount accepted for transaction.
Default: 500000.00
description
required
The description of the payment.
deposit_account_id Specify the recipient's deposit account id of the payment. Not required for accounts with only one deposit account.
access_token Load an existing payer's account settings. See the persistent accounts section for more information.
invoice_id If utilizing the invoice api, pass the desired invoice id.
recurring_invoice_id If utilizing the recurring invoice API and autopay, pass the desired recurring invoice id.
cards Use true or false to specify whether card payments are allowed. Default is true.
ach Use true or false to specify whether ACH payments are allowed. Default is true.
email The payer's email address, if available.
full_name The payer's full name, if available.
autopay Use true or false to specify whether autopay is allowed. Default is false.
custom_fields Transaction custom fields JSON object. *Example: {"example":"data"}
embed If true, embeds the plugin directly on the page.
embed_container The html container on the page where the plugin will be embedded.
bind_to_form Specify a form element to auto-submit with the transaction id once a payment is complete.

Deposit Plugin

Copy to Clipboard
<script src="https://placepay.com/plugins/deposit.js" data-key="public_key_AWcpDnNBB7oLfNqfQ6g66262" data-access-token="access_token_AWcpDnNBB7oLfNqfQ6g66262"> </script>

If you have a platform and are creating an end-to-end integration of PlacePay, you'll need to use the Deposit plugin to capture the deposit details for a new recipient's deposit account.

The Deposit plugin will embed a button onto your page that will allow access to a secure popup modal where an account holder can enter their desired direct deposit details.

Copy to Clipboard
<script> Place.deposit.open({ key: "public_key_AWcpDnNBB7oLfNqfQ6g66262", access_token: "${access_token}", deposit_account_id:"9hUFlPbqPlAUbeTp", on: { deposit_changed: function (data) { // handle callback } } }) </script>

Example

Below is an example of the Deposit plugin. You can click the button to see an example of the modal.

You can also launch the plugin from javascript instead of using the embedded html button by calling Place.deposit.open(), as seen in the example.

Create an Account

Copy to Clipboard
# Create a recipient account curl "https://api.placepay.com/deposit_accounts/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d company="Example Landlord LLC" \ -d phone="111-222-3333" \ -d address[street_address]="123 Example St" \ -d address[unit_number]="#4" \ -d address[city_state_zip]="New York, NY 10004"

First you need to create a deposit account.


Load the Deposit Button

Copy to Clipboard
# Create an access token curl "https://api.placepay.com/access_tokens" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d type=session_access
Copy to Clipboard
<script src="https://placepay.com/plugins/deposit.js" data-key="public_key_JqZzahBa9Z0exkzbQoEBl8" data-access-token="${access_token}"> </script>

The Deposit plugin requires a new session_access token each time you load the plugin.

The token must be created with the account id of the recipient. You'll need to create a new access-token every time a new Deposit button is loaded.


Javascript Callbacks

Copy to Clipboard
<script> Place.deposit.on( '.mybutton', 'loaded', function() { console.log('event captured') }) </script>

If you want to watch for a response from the plugin, to see whether a certain event was triggered, there are several available callbacks: deposit_changed, closed, loaded


Processing Activation

Copy to Clipboard
# Get the processing activation status deposit_account_id = 'hzus4iw9ujkR9TPcpYEs' curl "https://api.placepay.com/deposit_accounts/$deposit_account_id" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: | python -mjson.tool | grep processing_activation_status

A new deposit_method will generally become active for payment processing within 24 business hours but in some cases it can take longer or require additional information.

You can track the progress of the activation of a new deposit_method using the processing_activation_status field, which will relay the current status. Details on the different statuses are below:

Status Description
pending The new deposit method is pending activation. No delays or issues have been identified currently and the account should be active within 24 business hours.
in_review The deposit method has been escalated to require a further review. This can take 2-5 business days.
action_needed Further information is required by the account holder before activation.
active The deposit method is active for payment processing.
inactive The deposit method has been deactivated and is no longer able to accept payments.

Configuration

Parameter Description
data-key
required
Your public API key
data-deposit-account-id Specify the deposit account id. Not required for accounts with only one deposit account.
data-access-token Token for session access to an account. See the access-token section for more information.
data-btn-class Custom CSS class for the deposit button.
data-btn-text Custom text for the deposit button.

Payments & Transactions

The transactions object is the generic object for all types of transactions that occur within the system.

Transaction Types and States

Transaction Type Description
charge A customer's payment.
deposit A settlement of processed charges sent to a recipient's deposit account.
refund A return of either a full or partial amount from a charge.
reversal A reversal of either a full or partial amount from a deposit account for any refunds or chargebacks.
chargeback A return of funds to the customer from a disputed card payment.
chargeback_reversal The return of funds to the recipient from a successfully won chargeback dispute.
Transaction Status Description
authorized A transaction that has authorized but won't be captured until set to complete.
complete A transaction that has processed successfully.
canceled A submitted transaction that was voided before the funds were captured.
declined A transaction that was not able to process successfully.
failed A bank account payment received a failure message from the originating bank.

Ledger Details and Deposits

All transactions have both a credit_ledger and a debit_ledger. These ledgers outline how an individual transaction is associated with other transactions in the system.

Deposit batching

Automatic batching for deposits and reversals happens daily at 5:30pm Eastern Time. Charges will be batched based on the configured settlement timeframe for their associated deposit account. If a charge is associated with an invoice, the full or partial settlement configuration of that invoice will also be taken into account.


Charge details for a deposit

Copy to Clipboard
curl "https://api.placepay.com/transactions" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "fields=*,credit_ledger" \ -d "type=deposit" \ -d "account_id=$deposit_account_id"

To return the list of charges included in a deposit batch, in the return fields specify the credit_ledger embedded object field. You can expand the underlying source transaction to return the full transaction details embedded within each ledger object.


Deposit and refund details for a charge

Copy to Clipboard
curl "https://api.placepay.com/transactions" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "fields=*,debit_ledger"

To return the list of all associated deposits, refunds, etc. for any given charge, in the return fields specify the debit_ledger embedded object field.


Example transaction with ledger details

This is an example of a transaction with both debit_ledger and credit_ledger details. Notice there's an initial deposit made to the recipient, which is later refunded to the payer. Since the initial payment has been deposited, there is a reversal record in the credit_ledger.

Copy to Clipboard
{ "id": "HWIjDMdcZHl2Dj1i6lNXW4r5", "object": "transaction", "account_id": "r3jyJXI3bpLs9m9YZV6OiFib", "amount": 177.4, "deposit_account_id": "129BOlWKt2Ta52bU99hKZkH3C", "description": "string", "failed_timestamp": null, "fee": 1.95, "initiated_timestamp": "2018-05-10 12:32:18", "payment_method_id": "10f10tnMIIzFZkj7RDQvcCmVg", "status": "complete", "status_details": "string", "type": "charge", "debit_ledger": [{ "id": "115pm5D1vH0vjo2ftu5msX0Ns", "object": "transaction_ledger", "account_id": "1QsHK85NtiZZ0hDSTeZhzEAp6", "amount": 177.4, "destination_id": "1ct0dNO6EsKwzWCblbLoCSwrr", "source_id": "HWIjDMdcZHl2Dj1i6lNXW4r5", "status": "complete", "timestamp": "2018-05-10 12:32:18", "total_amount": 2101.36, "type": "deposit" },{ "id": "115pm5D1vH0vjo2ftu5msX0Ns", "object": "transaction_ledger", "account_id": "1QsHK85NtiZZ0hDSTeZhzEAp6", "amount": 177.4, "destination_id": "1ct0dNO6EsKwzWCblbLoCSwrr", "source_id": "HWIjDMdcZHl2Dj1i6lNXW4r5", "status": "complete", "timestamp": "2018-05-11 12:32:18", "total_amount": 177.4, "type": "refund" }], "credit_ledger": [{ "id": "115pm5D1vH0vjo2ftu5msX0Ns", "object": "transaction_ledger", "account_id": "1QsHK85NtiZZ0hDSTeZhzEAp6", "amount": 177.4, "destination_id": "HWIjDMdcZHl2Dj1i6lNXW4r5", "source_id": "1xfI91OI3EVPP57iKi5Iwobg0", "status": "complete", "timestamp": "2018-05-11 12:32:18", "total_amount": 300.3, "type": "reversal" }] }

Include the corresponding transaction details

Copy to Clipboard
curl "https://api.placepay.com/transactions" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "fields[self]=*,credit_ledger" \ -d "fields[credit_ledger][self]=*,source" \ -d "type=deposit" \ -d "account_id=$deposit_account_id"

You can expand the corresponding destination or source transaction to return the full transaction details embedded within each ledger object in a single request.


Voids and Refunds

Voids

Copy to Clipboard
curl "https://api.placepay.com/transactions/14qmPCuDo9lY1TI82kpLM6cKo" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d "status=canceled"

To void or cancel a recent transaction, you can simply update the status to canceled. In the event a transaction is no longer voidable, a refund can be attempted.


Refunds

Copy to Clipboard
curl "https://api.placepay.com/transactions/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "type=refund" \ -d "amount=1000" \ -d "credit_ledger[0][source_id]=14qmPCuDo9lY1TI82kpLM6cKo"

To initiate a refund, you need the original transaction id. The amount can be less than or equal to the net amount of the original transaction, less any refunds already processed.


Bank Account Transaction Failures

Copy to Clipboard
# Example of using the `greater-than` operator curl "https://api.placepay.com/transactions/?status=failed&failed_timestamp=>2017-11-01" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

Unlike cards, bank account payments (ACH payments) can fail days after a user initiates the payment. If a failure is reported by the originating bank, you can pull information through the API using the example.

You can also subscribe to the ach_failure event to be instantly notified when a bank account failure is received.


Chargebacks

Copy to Clipboard
curl "https://api.placepay.com/transactions/?type=chargeback&initiated_timestamp=>2018-05-01&fields=*,credit_ledger" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

You can track any disputed charges that resulted in a chargeback by querying the api by type chargeback. If the chargeback is later reversed in the recipients favor, a chargeback_reversal transaction will be linked to the original charge's credit_ledger.

You can also subscribe to the chargeback and chargeback_reversal events to be instantly notified when an adjustment is received.


Transaction Fees

Copy to Clipboard
curl "https://api.placepay.com/transactions/14qmPCuDo9lY1TI82kpLM6cKo?field=*,payer_conv_fee" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

Transaction fees can be paid by the payer, covered by the recipient, or split at any desired allocation. The fee settings are configured for the deposit account or invoice that the transaction is associated with. Fees can be adjustable based on debit, credit, and bank account payments.

The fee field in the transaction object represents the resulting cost to the recipient of the funds. To retrieve the fee charged to the payer, you can specify the addition of the payer_conv_fee field in the API request.


Testing

Test card transactions

To test card transactions with the test API keys, you can use any valid card number format. Any expiration, address, and CVV code will be accepted for test transactions.

Example valid card numbers:

4111 1111 1111 1111

4444 3333 2222 1111

5100 2900 2900 2909

Special card number to test declines:

5555 5555 5555 4444

Test bank account transactions

To test bank account transactions with the test API keys, the account number can be any numeric string. The routing number, however, must be any valid routing number.


Transaction Events

Copy to Clipboard
curl "https://api.placepay.com/events/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d "callback_url=https://example.com/ach_failure_handler" \ -d "event=ach_failure"

Event Example

Copy to Clipboard
{ "event": "ach_failure", "callback_url": "https://example.com/callback", "transaction_id": "1CBtYAuEpM1sBAF21Qb8QAKqk" }

There are multiple events that can trigger a custom callback url using the events endpoint for immediate notification to your app or platform.

Event Description
automatic_payment The automatic_payment event is triggered when a payment attempt is made automatically for an invoice. Note: this event will fire regardless of whether the payment was successful or not.
ach_failure The ach_failure event is triggered when an initiated ACH payment receives a failure response from the issuing bank.
refund The refund event is triggered every time any payment is refunded, regardless of whether it's through the API or the dashboard.
void The void event is triggered every time any payment is voided, regardless of whether it's through the API or the dashboard.
chargeback The chargeback event is triggered when an initiated card payment receives a chargeback response from the issuing bank.
chargeback_reversal The chargeback_reversal event is triggered when a chargeback of a card payment has been overturned in recipient's favor.

Invoicing

Copy to Clipboard
# Create a recurring invoice curl "https://api.placepay.com/recurring_invoices/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d start_date="2017-01-01" \ -d end_date="2017-12-31" \ -d recurring_frequency="recipient" \ -d invoice_template[type]="rent" \ -d invoice_template[deposit_account_id]="rent" \ -d invoice_template[items][0][type]="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA" \ -d invoice_template[items][0][amount]=1000 \ -d invoice_template[items][1][type]="ammenity" \ -d invoice_template[items][1][amount]=50 \ -d invoice_template[items][1][date_incurred]="2017-02-15" \ -d invoice_template[payers][0][account_id]=$account_id

Recurring Invoices

The recurring invoice API is an easy way to setup and manage recurring billing instructions. Invoices can be set to auto-generate, based on monthly or weekly schedules, and can handle multiple recurring invoice items with varying start dates, as well as multiple payers.

You can utilize the Pay plugin's autopay capabilities, along with the recurring invoice api, to take advantage of our fully automated autopay system by passing the data-recurring-invoice-id plugin parameter.


Copy to Clipboard
# Create a one-time invoice curl "https://api.placepay.com/invoices/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d type="rent" \ -d due_date="2018-01-01" \ -d deposit_account_id="rent" \ -d items[0][type]="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA" \ -d items[0][amount]=1000 \ -d items[1][type]="ammenity" \ -d items[1][amount]=50 \ -d items[1][date_incurred]="2017-02-15" \ -d payers[0][account_id]=$account_id

One-time Invoices

One-time invoices can be created for nonrecurring bills. Note, one-time invoice items can be added to invoices generated automatically by a recurring invoice


Copy to Clipboard
# Create a one-time invoice curl "https://api.placepay.com/invoices/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d type="rent" \ -d due_date="2018-01-01" \ -d deposit_account_id="rent" \ -d items[0][type]="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA" \ -d items[0][amount]=1000 \ -d items[0][allocations][0][account_id]=$account1_id \ -d items[0][allocations][0][amount]=600 \ -d items[0][allocations][1][account_id]=$account2_id \ -d items[0][allocations][1][amount]=400 \ -d payers[0][account_id]=$account1_id \ -d payers[1][account_id]=$account2_id

Multipayer Invoices

Multipayer invoices allow the payment of an invoice to be split across multiple payer accounts. The allocation of each item can be divvied up among the payers, and each payer allocation can be set to a locked custom amount or an evenly distributed auto allocation.

In a multi-payer scenario, invoices can be set to either a full or partial settlement configuration. In a full configuration, payments for that invoice won't settle until all payers have paid their portion in full, whereas in a partial settlement configuration, any payment made will be settled independently of any outstanding amount due by another payer.


Copy to Clipboard
# Create a prorated recurring invoice curl "https://api.placepay.com/recurring_invoices/" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -d start_date="2018-01-15" \ -d end_date="2018-12-31" \ -d prorated=true \ -d recurring_frequency="recipient" \ -d invoice_template[type]="rent" \ -d invoice_template[deposit_account_id]="rent" \ -d invoice_template[items][0][type]="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA" \ -d invoice_template[items][0][amount]=1000 \ -d invoice_template[items][1][type]="ammenity" \ -d invoice_template[items][1][amount]=50 \ -d invoice_template[items][1][date_incurred]="2017-02-15" \ -d invoice_template[payers][0][account_id]=$account_id

Prorated Invoice Items

The invoicing API has a built in prorate tool. If you enable prorated items for a recurring invoice, each item will be prorated on the first and last invoice that applies to that charge. The number of days that a charge is prorated is based on either the start date of the recurring invoice schedule, or the date the charge was incurred, if specified.


Paying an invoice

To submit a payment attempt and associate it with an invoice, use the transaction_allocation object allocating an amount to an invoice payer.

Copy to Clipboard
# Using curl, you can pass the API key with each request curl -s "https://api.placepay.com/transactions" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:\ -X POST \ -d account_id=1Xu7W8Ch6a8gnin5M \ -d amount=100 \ -d type=charge \ -d invoice_payer_allocations[0][amount]=100 \ -d invoice_payer_allocations[0][invoice_payer_id]=1chTLrLW6CboFiSNs \ -d fields="*,invoice_payer_allocations"

Properties

Get units, leases, invoices

Copy to Clipboard
# Using curl, you can pass the API key with each request curl -s "https://api.placepay.com/units" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:

Calling GET /units will return a list of all units and their leases, tenants, invoices, and invoice items.

The units list returned includes all subobjects.

Update a lease

Copy to Clipboard
# Using curl, you can pass the API key with each request curl -s "https://api.placepay.com/units/<unit_id>/leases" \ -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \ -X PUT \ -d due_day=1

You can pass back the same object with any updates to the hierarchy in and PUT call.


Adding a lease

You can pass back the same object with any new objects to the hierarchy with a PUT call. This will create any new objects found in the hierarchy.


Delete lease

You can pass back the same object with any objects removed from hierarchy with a PUT call. This will delete any missing objects from the resulting hierarchy.


Object reference

Accounts

This endpoint retrieves all accounts.

Resource

https://api.placepay.com/accounts

Embedded Resources

https://api.placepay.com/accounts/{id}/access_tokens

https://api.placepay.com/accounts/{id}/deposit_accounts

https://api.placepay.com/accounts/{id}/custom_fields

Fields

Object example

Copy to Clipboard
{ "id": "1WwnZk3OnInAVEW9bDA2rZ8rf", "object": "account", "accepted_terms": false, "company": "string", "email": "joe.chip@example.com", "full_name": "Joe Chip", "phone": "(123) 456-7890", "user_type": "string" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: account
accepted_terms
bool
Flag for if the user has accepted the user agreement
company
string
Company name of account holder
email
email
required
Email address of account holder
full_name
string
required
Name of account holder
phone
phone
Phone number of account holder
user_type
string
readonly: update
Either payer or recipient

Deposit Accounts

This endpoint retrieves all deposit_accounts.

Resource

https://api.placepay.com/deposit_accounts

Embedded Resources

https://api.placepay.com/deposit_accounts/{id}/deposit_method

https://api.placepay.com/deposit_accounts/{id}/custom_fields

https://api.placepay.com/deposit_accounts/{id}/address

Fields

Object example

Copy to Clipboard
{ "id": "fpuDkgwvSVftuG6hS7zi4q8i", "object": "deposit_account", "accepted_terms": true, "address": {}, "address_id": "B5yPEqeQYq634MErw0INpWHr", "company": "string", "default": true, "deposit_method": {}, "deposit_method_id": "25aa0XQAMYqezsOTV6ZNOiiKA", "phone": "(123) 456-7890", "required_payer_auth_level": 2, "transaction_limit": "float", "fee_settings": { "bank_account": { "distribution": 1.0, "flat": 1.95, "pct": 0.0 }, "credit": { "distribution": 0.0, "flat": 0.0, "pct": 0.0299 }, "debit": { "distribution": 0.0, "flat": 0.0, "pct": 0.0299 } } }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: deposit_account
accepted_terms
bool
Flag for if the signer has accepted the processing agreements
address
object
required
Single address object
address_id
id
readonly
Id for address object
company
string
required
Company name of deposit account
default
bool
Denotes if this account is the user's specified default
deposit_method
object
Single payment_methods object
deposit_method_id
id
Id for payment_method object
phone
phone
required
Phone number associated with the deposit account
required_payer_auth_level
bool
readonly: user_sessions
Minimum authorisation level for payers to this deposit account. Defaults to 2
transaction_limit
float
readonly
None
fee_settings:  
bank_account:  
distribution
number
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
credit:  
distribution
number
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
debit:  
distribution
number
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
 

Access Token

This endpoint retrieves all access_token.

To create an access token the account holder's secret key is required to be passed via HTTP Basic Auth.

Example create

Copy to Clipboard
curl -X POST "https://api.rentshare.com/accounts/43242/account_token" -u api_key_6fsMi3GDxXg1XXSluNx1sLEd:secret_key_JIgOLxPqSV9bROAL

Resource

https://api.rentshare.com/access_token

Fields

Object example

Copy to Clipboard
{ "id": "24aJtyGMNkjIUJ6rhJJDZr5XM", "object": "access_token", "access_token": "string", "account_id": "3cWtpxgezXzo2pRGObmx6eHA", "expiration": "2018-01-21 16:16:23", "type": "private_key" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: access_token
access_token
string
readonly
Access token to be used for api access
account_id
id
readonly
Id for account object
expiration
datetime
Date and time access token will expire
type
string
required
Valid values: private_key, user, session_access, public_key

Account Permissions

This endpoint retrieves all account_permissions.

Resource

https://api.placepay.com/account_permissions

Fields

Object example

Copy to Clipboard
{ "id": "ZFiU4yT9Ux92qHBAi0EYXwaX", "object": "account_permission", "account_id": "1FT0UgDzNdWvGogrkNVm78iC8", "method": "GET", "resource": "string" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: account_permission
account_id
id
readonly
Id for account object
method
string
required
Valid values: GET, POST, PUT, DELETE, *
resource
string
required
Resource path, e.g. /transactions

Transactions

This endpoint retrieves all transactions.

Resource

https://api.placepay.com/transactions

Embedded Resources

https://api.placepay.com/transactions/{id}/reversals

https://api.placepay.com/transactions/{id}/credit_ledger

https://api.placepay.com/transactions/{id}/debit_ledger

https://api.placepay.com/transactions/{id}/invoice_payer_allocations

https://api.placepay.com/transactions/{id}/payment_method

https://api.placepay.com/transactions/{id}/transfers

https://api.placepay.com/transactions/{id}/custom_fields

Fields

Object example

Copy to Clipboard
{ "id": "1gOwTYruaRmghwAXqwtX8meUJ", "object": "transaction", "account_id": "h6wQ3lj1glKroDyaC9Eqci28", "amount": 79.55, "amount_min": 35.00, "amount_max": 900.00, "deposit_account_id": "F68URveHAXl1RwGnprsr8DMP", "description": "string", "failed_timestamp": "2018-08-22 13:38:08", "fee": 1.95, "initiated_timestamp": "2018-08-22 13:38:08", "invoice_payer_allocations": [], "payment_method": {}, "payment_method_id": "RiobId4cHhczUcJhWsuzv0v8", "settled": false, "status": "pending", "status_details": "string", "type": "charge" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: transaction
account_id
id
readonly: update
Id for account object
amount
number
readonly: update
Amount of the payment
amount_min
number
Minimum payment amount accepted for transaction.
Default: 0.01
amount_max
number
Maximum payment amount accepted for transaction.
Default: 500000.00
deposit_account_id
id
readonly: update
Id for deposit account object
description
string
Description of the payment
failed_timestamp
datetime
readonly
Date the payment failed (ACH Only)
fee
number
readonly: user_sessions,update
Processing fee
initiated_timestamp
datetime
readonly
Date the payment was initiated
invoice_payer_allocations
list
List of transaction_allocations objects
payment_method
object
Single payment_methods object
payment_method_id
id
readonly: update
Id for payment_method object
settled
bool
readonly
Denotes if the payment has settled
status
string
Valid values: pending, complete, declined, canceled, failed
status_details
string
readonly: user_sessions
Additional details on the status of the payment
type
string
readonly: update
Valid values: charge, deposit, reversal, refund, chargeback, chargeback_reversal

Transaction Allocations

This endpoint retrieves all transaction_allocations.

Resource

https://api.placepay.com/transaction_allocations

Fields

Object example

Copy to Clipboard
{ "id": "25si9BOqSzgvD9xPHLxcPMdLO", "object": "transaction_allocation", "amount": 502.57, "invoice_description": "string", "invoice_id": "tw6iUk1nm2j8BPxiMRR5G8Ha", "invoice_payer_id": "1xIRYJHXVLiNu4kLvzY9gqIuQ", "status": "string", "timestamp": "2018-08-22 13:38:08", "transaction_id": "1QXTxVurSNdoMUuxodmUSriNv" }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: transaction_allocation
amount
number
required
Amount allocated to the referenced invoice payer
invoice_description
string
readonly
Invoice description
invoice_id
id
readonly
Id for invoice object
invoice_payer_id
id
required
Id for invoice_payer object
status
string
readonly
The current status of the transaction
timestamp
datetime
readonly
The timestamp of the transaction
transaction_id
id
required
Id for transaction object

Transaction Ledger

This endpoint retrieves all credit_ledgers.

Resource

https://api.placepay.com/credit_ledgers

Embedded Resources

https://api.placepay.com/credit_ledgers/{id}/source

Fields

Object example

Copy to Clipboard
{ "id": "27FRnUePmHnVEfarGI10OE9R7", "object": "transaction_ledger", "account_id": "kGvJbSmy6AJBQkAGBLvrnywu", "amount": 828.9, "destination_id": "1q4x3VZbLeOvnrSkccy8Go8Ug", "source_allocation_id": "SC0ZJxENtHkx55iZtxpvl26b", "source_id": "233bgJQ6DMRAIGSUe0esPm7Fm", "status": "complete", "timestamp": "2018-08-22 13:38:08", "total_amount": 209.76, "type": "charge", "viewpoint": "string" }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: transaction_ledger
account_id
id
readonly
Id for account object
amount
number
Amount of ledger transfer
destination_id
id
readonly
Id for destination object
source_allocation_id
id
Id for source_allocation object (if applicable)
source_id
id
required
Id for source object
status
string
readonly
Status of transaction
timestamp
datetime
readonly
Timestamp of transaction
total_amount
number
readonly
Total resulting transaction amount
type
string
readonly
Type of transaction
viewpoint
string
readonly
None

Payment Methods

This endpoint retrieves all payment_methods.

Resource

https://api.placepay.com/payment_methods

Embedded Resources

https://api.placepay.com/payment_methods/{id}/billing_address

https://api.placepay.com/payment_methods/{id}/processor_approval

Fields

Object example

Copy to Clipboard
{ "id": "zfqPG3IR2EpX7RCmYf6rk0nR", "object": "payment_method", "account_id": "I31sdrQugh4TExONRAF69LYJ", "ach_processing_approval": false, "allowed_transaction_types": "charge", "authorized": 486, "billing_address": {}, "billing_address_id": "ZZqKk8Qpu1tblVG4W1jMow9z", "birth_date": "2018-08-22", "card_processing_approval": true, "company": "string", "website_url": "https://www.example.com/", "established": "2009-04-10 00:00:00", "building_type": "Residential", "unit_count":200, "monthly_volume": 301, "highest_monthly": 6500, "company_ownership": 593.65, "company_type": "string", "date_created": "2018-08-22 13:38:08", "deleted": false, "description": "string", "ein": "string", "first_name": "string", "last_name": "string", "phone_number": "(123) 456-7890", "processing_activation_status": "pending", "processor_approval": {}, "processor_approval_id": "Sd3cqUqCt3AjsaLIo9F9kYui", "ssn": "string", "type": "card", "bank_account": { "account_class": "string", "account_number": "string", "account_type": "string", "routing_number": "string" }, "card": { "card_brand": "string", "card_code": "string", "card_number": "string", "card_type": "credit", "expiration_date": "2018-08-22" } }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: payment_method
account_id
id
required
Id for account object
ach_processing_approval
bool
readonly: user_sessions
Denotes if ach payments has been approved. For disbursable payments methods only
allowed_transaction_types
string
readonly: update
Valid values: charge, charge,disburse
authorized
int
readonly: user_sessions
Denotes the authorization level of this payment method
billing_address
object
Single address object
billing_address_id
id
readonly
Id for address object
birth_date
date
Birth date of the account holder
card_processing_approval
bool
readonly: user_sessions
Denotes if card payments has been approved. For disbursable payments methods only
company
string
required
The legal entity name associated with the account
company_ownership
number
required
The ownership percentage of the legal entity
company_type
string
required
The legal entity type, i.e., LLC
date_created
datetime
readonly
The timestamp the payment method was added to the system
deleted
bool
readonly: create
Identifies if the payment method has been deleted or deactivated.
description
string
readonly
A human-readable description of the payment method, i.e., Visa x-4242
ein
string
required
The legal entity tax id. For disbursable payments methods only
first_name
string
required
The first name of the account holder
last_name
string
required
The last name of the account holder
phone_number
phone
required
The phone number of the account holder
processing_activation_status
string
readonly
Valid values: pending, in_review, active, inactive, action_needed
processor_approval
object
Single processing_account object
processor_approval_id
id
readonly
Id of underlying processing object
ssn
string
required
The principal's social security number. For disbursable payments methods only
type
string
required
Valid values: card, bank_account
bank_account:  
account_class
string
readonly: update
None
account_number
string
readonly: restricted_update
None
account_type
string
readonly: restricted_update
None
routing_number
string
readonly: restricted_update
None
 
card:  
card_brand
string
readonly
None
card_code
string
None
card_number
string
readonly: update
None
card_type
string
readonly: user_sessions
Valid values: credit, debit
expiration_date
date
required
None
 

Autopay Enrollments

This endpoint retrieves all autopay_enrollments.

Resource

https://api.placepay.com/autopay_enrollments

Fields

Object example

Copy to Clipboard
{ "id": "gQ0HHiJrZ1ZanNcGfIvAaw2r", "object": "autopay_enrollment", "account_id": "MfHb7CbANIWs3oDYLfyT4NC1", "deposit_account_id": "E98VpXS83zzXKA8Hx7ijbzPc", "enrolled_timestamp": "2018-08-22 13:38:08", "last_payment_status": "string", "last_payment_timestamp": "2018-08-22 13:38:08", "lower_limit": 233.37, "payment_method_id": "10TYcywq1HI04qNx09Cd8fgyg", "recurring_invoice_id": "22GY0oo4aHY8CpVo8kBjIzvmt", "upper_limit": 845.6 }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: autopay_enrollment
account_id
id
readonly
Id for account object
deposit_account_id
id
Id for deposit_account object
enrolled_timestamp
datetime
readonly
Timestamp user enrolled in autopay
last_payment_status
string
readonly
Status of the last payment attempt for the account
last_payment_timestamp
datetime
readonly
Timestamp of the last payment attempt for the account
lower_limit
currency
Lower limit of how much the user has allowed to auto-process
payment_method_id
id
required
Id for payment_method object
recurring_invoice_id
id
readonly: update
Id for recurring_invoice object
upper_limit
currency
required
Upper limit of how much the user has allowed to auto-process

Events

This endpoint retrieves all events.

Resource

https://api.placepay.com/events

Fields

Object example

Copy to Clipboard
{ "id": "1pOw6dUon3NZ8WmgQ9KGWpGkd", "object": "event", "callback_url": "https://example.com/ach_failure_handler", "event": "ach_failure" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: event
callback_url
string
required
Url to trigger
event
string
required
Name of event

Recurring Invoices

This endpoint retrieves all recurring_invoices.

Resource

https://api.placepay.com/recurring_invoices

Embedded Resources

https://api.placepay.com/recurring_invoices/{id}/invoices

https://api.placepay.com/recurring_invoices/{id}/invoice_template

Fields

Object example

Copy to Clipboard
{ "id": "vIxM2IRzBwScnoS1DR2azJsW", "object": "recurring_invoice", "autogenerate_buffer": 87, "autogenerate_invoices": true, "cycle_offset": 1, "deposit_account_id": "VKVYqLtAgaSa5KLIUzmc82rz", "end_date": "2018-08-22", "invoice_template": {}, "invoice_template_id": "1yAULJ2cPp2weN6k5nkwfnPgq", "invoices": [], "prorated": true, "recurring_frequency": "monthly", "start_date": "2018-08-22" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: recurring_invoice
autogenerate_buffer
int
None
autogenerate_invoices
bool
Denotes whether new invoices will be automatically generated
cycle_offset
int
Day of the month rent is due
deposit_account_id
id
None
end_date
date
End date of the recurring service period
invoice_template
object
required
Single invoice object
invoice_template_id
id
readonly
None
invoices
list
List of invoice objects
prorated
bool
If enabled, initial and final charges will be prorated
recurring_frequency
string
Valid values: monthly, weekly
start_date
date
Start date of the recurring service period

Invoices

This endpoint retrieves all invoices.

Resource

https://api.placepay.com/invoices

Embedded Resources

https://api.placepay.com/invoices/{id}/items

https://api.placepay.com/invoices/{id}/payers

https://api.placepay.com/invoices/{id}/custom_fields

https://api.placepay.com/invoices/{id}/payment_records

Fields

Object example

Copy to Clipboard
{ "id": "brLufAn5APd2791lj1nRPoej", "object": "invoice", "accepted_payment_state": "full", "amount": 1000, "amount_paid": 1000, "amount_unallocated": 200, "completed_date": "2015-09-01", "deposit_account_id": 123, "description": "September Rent", "due_date": "2015-09-01", "items": [], "last_payment_date": "2018-08-22 13:38:08", "paid": true, "payers": [], "payment_records": [], "payments_blocked": false, "recurring_invoice_id": "AlH27xAPBqRCdzC9JWl7HQUa", "reference_id": "Acct #ABC-123", "required_payer_auth_level": 2, "type": "rent", "fee_settings": { "bank_account": { "distribution": 1.0, "flat": 1.95, "pct": 0.0 }, "credit": { "distribution": 1.0, "flat": 0.0, "pct": 0.0299 }, "debit": { "distribution": 1.0, "flat": 0.0, "pct": 0.0299 } } }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: invoice
accepted_payment_state
string
Denotes whether this invoice requires payment by all tenants. Can be 'partial' or 'full'
amount
number
readonly
Amount due on this invoice
amount_paid
number
readonly
The amount that has been paid by tenants
amount_unallocated
number
readonly
Amount on this invoice that has not been allocated to individual tenants
completed_date
datetime
readonly
Date on which this invoice was paid
deposit_account_id
id
Id for deposit account object
description
string
Description for this invoice
due_date
date
required
The due date for this invoice
items
list
required
List of invoice_items objects
last_payment_date
datetime
readonly
Date and time of the last payment made on this invoice
paid
bool
readonly
Denotes whether this invoice has been paid
payers
list
List of invoice_payers objects
payment_records
list
List of invoice_payment_records objects
payments_blocked
bool
Denotes whether payments are allowed on this invoice
recurring_invoice_id
id
Id for recurring invoice object
reference_id
string
Copied from reference_id defined in lease
required_payer_auth_level
bool
readonly
Minimum authorisation level for payers on this invoice. Defaults to 2
type
string
required
Invoice type, such as rent, fee, misc, etc.
fee_settings:  
bank_account:  
distribution
number
readonly
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
credit:  
distribution
number
readonly
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
debit:  
distribution
number
readonly
Denotes the fee distribution between payee and payer
flat
number
readonly
Flat fee for processing a payment
pct
number
readonly
Percent fee for processing a payment
 
 

Invoice Payers

This endpoint retrieves all invoice_payers.

Resource

https://api.placepay.com/invoice_payers

Embedded Resources

https://api.placepay.com/invoice_payers/{id}/transaction_allocations

https://api.placepay.com/invoice_payers/{id}/payments

Fields

Object example

Copy to Clipboard
{ "id": "1jhcsVzB1jvv47nu4sNvojj9E", "object": "invoice_payer", "access": true, "account_id": "yos62Ggb43JZsccLD8cZ0e56", "active": true, "amount_allocated": 1000, "amount_paid": 1000, "email": "joe.chip@example.com", "first_name": "Joe", "invoice_id": "LQ8stUFNG1p5lVWX1Lpn6oH6", "last_name": "Chip", "last_payment_date": "2015-08-28", "paid": true, "payments_transfer_date": "2015-09-04", "payments_transfered": true, "transaction_allocations": [] }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: invoice_payer
access
bool
required
Denotes whether this payer has been authorized access this invoice
account_id
id
readonly: update
Id for account object
active
bool
readonly
Denotes whether this payer is still active
amount_allocated
number
readonly
The amount assigned to this payer for this invoice
amount_paid
number
readonly
The amount this payer has paid for this invoice
email
email
required
Email address of account holder
first_name
string
required
First name of account holder
invoice_id
id
readonly: update
Id for invoice object
last_name
string
Last name of account holder
last_payment_date
datetime
readonly
The last payment made by this payer for this invoice
paid
bool
readonly
Denotes whether this payer has paid
payments_transfer_date
datetime
readonly
The date on which the payments made by this payer were transferred to the payee
payments_transfered
bool
readonly
Denotes whether the payments made by this payer have been transferred to the payee
transaction_allocations
list
List of transaction_allocations objects

Invoice Items

This endpoint retrieves all invoice_items.

Resource

https://api.placepay.com/invoice_items

Embedded Resources

https://api.placepay.com/invoice_items/{id}/custom_fields

https://api.placepay.com/invoice_items/{id}/allocations

Fields

Object example

Copy to Clipboard
{ "id": "CA98I5I66SjsEQmIINjdExJe", "object": "invoice_item", "allocations": [], "amount": 100, "amount_allocated": 100, "classifier": "charge", "date_incurred": "2018-08-22 13:38:08", "description": "Wolf Chow", "invoice_id": "21MjSZMeU9LAQ488UNy7wkg1S", "prorated": false, "recurring": false, "type": "Shared Expense" }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: invoice_item
allocations
list
readonly
List of invoice_item_allocation objects
amount
number
required
The amount for this invoice item
amount_allocated
number
readonly
The amount of this invoice item that has been assigned to payers
classifier
string
Valid values: charge, payment
date_incurred
datetime
Date the invoice item was incurred
description
string
The description for this invoice item
invoice_id
id
readonly: update
Id for invoice object
prorated
bool
readonly
Date the invoice item was incurred
recurring
int
Denotes whether this item recurs monthly or is a one-time item
type
string
The type of this invoice item, ie. Rent, Late Fee, etc.

Invoice Item Allocations

This endpoint retrieves all invoice_item_allocations.

Resource

https://api.placepay.com/invoice_item_allocations

Fields

Object example

Copy to Clipboard
{ "id": "197blt1KHVfRSxSm7q6nOadvE", "object": "invoice_item_allocation", "amount": 100, "item_id": "1LqZzG0dz1ao4hOfMegAlsaB3", "payer_id": "BQZZeTNbynKYop9spC8E8VNn", "type": "auto" }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: invoice_item_allocation
amount
number
required
The amount of this assignment
item_id
id
readonly
Id for invoice item object
payer_id
id
readonly
Id for invoice payer object
type
string
required
The type of this assignment. Can be 'auto', 'custom', 'auto_payer', or 'auto_payee'

Addresses

This endpoint retrieves all addresses.

Resource

https://api.placepay.com/addresses

Fields

Object example

Copy to Clipboard
{ "id": "1o5jQjKWaEsaDElh1ArwiiNPb", "object": "address", "address": "123 Example St, #2F", "city_state_zip": "New York, NY 10001", "street_address": "123 Example St", "street_name": "Example St", "street_number": "123", "unit_number": "#2F" }
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: address
address
string
readonly
Full address and unit number, if applicable
city_state_zip
string
required
The city city, state and zipcode
street_address
string
required
The street number and name, this excludes any unit number
street_name
string
readonly
The name of the street
street_number
string
readonly
The street number
unit_number
string
The unit number, null if N/A

Units

This endpoint retrieves all units.

Resource

https://api.placepay.com/units

Embedded Resources

https://api.placepay.com/units/{id}/leases

https://api.placepay.com/units/{id}/address

Fields

Object example

Copy to Clipboard
{ "id": "AUtiNNdUlGOdYb5V3eQkrkWw", "object": "unit", "active": false, "address": {}, "address_id": 123, "billing_account_id": 123, "building_id": 123, "leases": [], "price": 1000, "status": "payments_allowed", "type": "rental" }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: unit
active
bool
readonly
None
address
object
readonly
Single address object
address_id
int
Id for address object
billing_account_id
int
readonly
Id for billing account object
building_id
int
Id for building object
leases
list
List of lease objects
price
number
Default rent amount for this unit
status
string
Verification status: payments_allowed, payments_blocked
type
string
Valid values: rental, condo

Leases

This endpoint retrieves all leases.

Resource

https://api.placepay.com/leases

Embedded Resources

https://api.placepay.com/leases/{id}/invoices

https://api.placepay.com/leases/{id}/conditional_rules

https://api.placepay.com/leases/{id}/recurring_items

https://api.placepay.com/leases/{id}/tenants

Fields

Object example

Copy to Clipboard
{ "id": 123, "object": "lease", "active": false, "amount": 1500, "autogenerate_invoices": true, "conditional_rules": [], "due_day": 1, "end_date": "2016-01-01", "invoices": [], "lease_document": "string", "payments_blocked": false, "prorated": false, "recurring_frequency": "monthly", "recurring_invoice_id": 123, "recurring_invoice_template_id": 123, "recurring_items": [], "reference_id": "Acct #ABC-123", "rent_amount": 1000, "start_date": "2015-06-06", "tenants": [], "type": "Acct #ABC-123", "unit_id": 123 }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: lease
active
bool
None
amount
number
readonly
Total due on this lease, including other items such as late fees
autogenerate_invoices
bool
Denotes whether new invoices will be automatically generated
conditional_rules
list
List of conditional_invoice_items objects
due_day
int
required
Day of the month rent is due
end_date
date
Date this lease ends
invoices
list
List of invoice objects
lease_document
string
Stored lease document file. Input format: Data URI
payments_blocked
bool
Denotes whether payments are allowed on this invoice
prorated
bool
If enabled, initial and final charges will be prorated
recurring_frequency
string
Valid values: monthly, weekly
recurring_invoice_id
int
readonly
Id for recurring invoice object
recurring_invoice_template_id
int
readonly
Id for recurring invoice template object
recurring_items
list
List of invoice_items objects
reference_id
string
User generated reference for this lease
rent_amount
number
readonly
Rent amount for this lease
start_date
date
Date this lease begins
tenants
list
required
List of tenant objects
type
string
User generated reference for this lease
unit_id
int
required
Id for unit object

Tenants

This endpoint retrieves all tenants.

Resource

https://api.placepay.com/tenants

Fields

Object example

Copy to Clipboard
{ "id": "1tj6F7aguw5dQh9KefpccGcpl", "object": "tenant", "account_id": 123, "active": true, "email": "joe.chip@example.com", "first_name": "Joe", "last_name": "Chip", "lease_id": 123, "mobile_enabled": true, "name": "string", "phone": "string", "recurring_payer_id": 601, "user_id": 123 }
Parameter Description
id
id
Unique object identifier
object
string
readonly
Valid values: tenant
account_id
int
readonly
Id for account object
active
bool
readonly
None
email
email
readonly: update
Email address of account holder
first_name
string
readonly: update
First name of account holder
last_name
string
readonly: update
Last name of account holder
lease_id
int
Id for lease object
mobile_enabled
bool
readonly
Denotes if user has push notification capabilities
name
string
readonly: update
Full name of resident
phone
string
Phone number of resident
recurring_payer_id
int
readonly
Id for recurring invoice_payer object
user_id
int
readonly
Id for user object