NAV Navbar
Logo
shell python ruby php javascript csharp

Introduction

# Live API url
https://api.placepay.com/
# Test API url
https://test-api.placepay.com/
# Live API
>>> import place
>>> place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
# Test API
>>> import place
>>> place.api_key = 'test_private_key_dwjVajaCQKO4RJuV'
# Live API
irb(main):001:0> require 'place'
irb(main):002:0> Place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
# Test API
irb(main):001:0> require 'place'
irb(main):002:0> Place.api_key = 'test_private_key_dwjVajaCQKO4RJuV'
<?php
# Live API
require_once('vendor/autoload.php');
Place\Place::$api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
?>
<?php
# Test API
require_once('vendor/autoload.php');
Place\Place::$api_url = 'test_private_key_dwjVajaCQKO4RJuV';
?>
> // Live API url
> var place = require('place');
> place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
> // Test API url
> var place = require('place');
> place.api_key = 'test_private_key_dwjVajaCQKO4RJuV'
// .NET Library is currently in beta
// Live API url
PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";
// Test API url
PlaceClient.api_key = "test_private_key_dwjVajaCQKO4RJuV";

The Place 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).

# To install from GitHub using pip:
pip install git+https://github.com/placepay/place-python.git

# To install using Bundler:
gem 'place', :git => 'git://github.com/placepay/place-ruby.git'

# To manually install `place-ruby` from github use gem specific_install:
gem install specific_install
gem specific_install https://github.com/placepay/place-ruby.git

# To install using Composer:
composer config minimum-stability dev
composer config repositories.place-php git https://github.com/placepay/place-php.git
composer require place/place-php:master

# To install using npm:
npm install git+ssh://git@github.com/placepay/place-node.git

https://github.com/placepay/place-csharp.git

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

# 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:
import place
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
require "place"
Place.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd"
<?php
require_once('vendor/autoload.php');
Place\Place::$api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";
?>
var place = require('place')
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'
PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

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

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

# Single mode
curl "https://api.placepay.com/transactions/gkXzxwqyMw7LWAIFJecc4I90" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
import place
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

# Single mode
transaction = place.Transaction.get('gkXzxwqyMw7LWAIFJecc4I90')
require "place"
Place.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd"

# Single mode
transaction = Place::Transaction.get('gkXzxwqyMw7LWAIFJecc4I90')
<?php
Place\Place::$api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

# Single mode
$transaction = Place\Transaction::get('gkXzxwqyMw7LWAIFJecc4I90');
?>
var place = require('place')
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

// Single mode
place.Transaction.get('gkXzxwqyMw7LWAIFJecc4I90')
    .then(function(transaction){})
PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

// Single mode
PlaceTransaction transaction = PlaceTransaction.get("gkXzxwqyMw7LWAIFJecc4I90");

Single mode

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

No request body


# Query mode
curl "https://api.placepay.com/transactions/?type=refund" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
# Query mode
transaction = place.Transaction.select( type='refund' )
# Query mode
transaction = Place::Transaction.select( :type => "refund" )
<?php
# Query mode
$transaction = Place\Transaction::select(array('type'=>'refund'));
?>
// Query mode
place.Transaction.select({ type: 'refund' })
    .then(function(transaction){})
// Query mode
PlaceTransaction transaction = PlaceTransaction.select(new { type="refund" });

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.

# Single mode
curl "https://api.placepay.com/accounts/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d email="joe.schmoe@example.com" \
    -d full_name="Joe Schmoe" \
    -d user_type="payer"
# Single mode
account = place.Account.create(
    email='joe.schmoe@example.com',
    full_name='Joe Schmoe',
    user_type='payer'
)
# Single mode
account = Place::Account.create(
    :email => 'joe.schmoe@example.com',
    :full_name => 'Joe Schmoe',
    :user_type => 'payer'
)
<?php
# Query mode
$account = Place\Account::create(array(
    'email'=>'joe.schmoe@example.com',
    'full_name'=>'Joe Schmoe',
    'user_type'=>'payer'
));
?>
// Single mode
place.Account.create({
    email: 'joe.schmoe@example.com',
    full_name: 'Joe Schmoe',
    user_type: 'payer'
}).then(function(account) {});
// Single mode
PlaceAccount account = PlaceAccount.create(new {
    email="joe.schmoe@example.com",
    full_name="Joe Schmoe",
    user_type="payer"
})

Single mode

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

Request body:

{ ... } single json object


# Bulk mode
curl "https://api.placepay.com/accounts/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d [0]email="joe.schmoe@example.com" \
    -d [0]full_name="Joe Schmoe" \
    -d [0]user_type="payer" \
    -d [1]email="jane.schmoe@example.com" \
    -d [1]full_name="Jane Schmoe" \
    -d [1]user_type="payer"
# Bulk mode
accounts = place.Account.create([
    place.Account(
        email='joe.schmoe@example.com',
        full_name='Joe Schmoe',
        user_type='payer'
    ),
    place.Account(
        email='jane.schmoe@example.com',
        full_name='Jane Schmoe',
        user_type='payer'
    )
])
# Bulk mode
accounts = Place::Account.create([
    Place::Account.new(
        :email => 'joe.schmoe@example.com',
        :full_name => 'Joe Schmoe',
        :user_type => 'payer'
    ),
    Place::Account.new(
        :email => 'jane.schmoe@example.com',
        :full_name => 'Jane Schmoe',
        :user_type => 'payer'
    )
])
<?php
# Bulk mode
$account = Place\Account::create(array(
    new Place\Account(array(
        'email'=>'joe.schmoe@example.com',
        'full_name'=>'Joe Schmoe',
        'user_type'=>'payer'
    )),
    new Place\Account(array(
        'email'=>'jane.schmoe@example.com',
        'full_name'=>'Jane Schmoe',
        'user_type'=>'payer'
    ))
));
?>
// Bulk mode
place.Account.create([
    place.Account({
        email: 'joe.schmoe@example.com',
        full_name: 'Joe Schmoe',
        user_type: 'payer'
    }),
    place.Account({
        email: 'jane.schmoe@example.com',
        full_name: 'Jane Schmoe',
        user_type: 'payer'
    })
]).then(function(account) {});
// Bulk mode
List<PlaceAccount> accounts = PlaceAccount.create(new[]{
    new PlaceAccount(){
        email="joe.schmoe@example.com",
        full_name="Joe Schmoe",
        user_type="payer"
    },
    new PlaceAccount(){
        email="jane.schmoe@example.com",
        full_name="Jane Schmoe",
        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.

# Single mode
curl "https://api.placepay.com/accounts/rqlPhhU3aJ8DWBF5zPJI8HrU" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT \
    -d email="joe.schmoe@newwork.com"
# Single mode
account.update( email="joe.schmoe@newwork.com" )
# Single mode
account.update( :email => 'joe.schmoe@example.com' )
<?php
# Single mode
$account->update(array( 'email'=>'joe.schmoe@example.com' ));
?>
// Single mode
account.update({ email: "joe.schmoe@newwork.com" })
// Single mode
account.update(new { email="joe.schmoe@newwork.com" });

Single mode

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

{ ... } single json object


# Query mode
curl "https://api.placepay.com/accounts/?email=joe.schmoe@example.com&query_mode=1" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT \
    -d email="joe.schmoe@newwork.com"
# Query mode
accounts = place.Account.select(
    email='joe.schmoe@example.com',
    update_all={
        'email': 'joe.schmoe@newwork.com'
    }
)
# Query mode
accounts = Place::Account.select(
    :email => 'joe.schmoe@example.com',
    :update_all => {
        'email' => 'joe.schmoe@newwork.com'
    }
)
<?php
# Query mode
$accounts = Place\Account::select(array(
    'email'=>'joe.schmoe@example.com',
    'update_all'=>array(
        'email'=>'joe.schmoe@newwork.com'
    )
));
?>
// Query mode
place.Account.select({
    email: 'joe.schmoe@example.com',
    update_all: {
        'email': 'joe.schmoe@newwork.com'
    }
})
// Query mode
List<PlaceAccount> accounts = PlaceAccount.select(new {
    email="joe.schmoe@example.com"
}, update_all: new {
    email="joe.schmoe@newwork.com"
});

Query mode (See the query language)

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

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


# Bulk mode
curl "https://api.placepay.com/accounts/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT \
    -d [0][id]="rqlPhhU3aJ8DWBF5zPJI8HrU" \
    -d [0][email]="joe.schmoe@newwork.com" \
    -d [1][id]="kswxX5hFW57SN7icmdcaszd4" \
    -d [1][email]="jane.schmoe@newwork.com"
# Bulk mode
accounts = place.Account.update_all([
    [ account1, { 'email': 'joe.schmoe@newwork.com' } ],
    [ account2, { 'email': 'james.schmoe@newwork.com' } ]
])
# Bulk mode
accounts = Place::Account.update_all([
    [ account1, { 'email': 'joe.schmoe@newwork.com' } ],
    [ account2, { 'email': 'james.schmoe@newwork.com' } ]
])
<?php
# Bulk mode
$accounts = Place\Account::update_all(array(
    array( account1, array( 'email'=>'joe.schmoe@newwork.com' )),
    array( account2, array( 'email'=>'james.schmoe@newwork.com' ))
));
?>
// Bulk mode
place.Account.update_all([
    [ account1, { 'email': 'joe.schmoe@newwork.com' } ],
    [ account2, { 'email': 'james.schmoe@newwork.com' } ]
])
// Bulk mode
List<PlaceAccount> accounts = PlaceAccount.update_all(new object[]{
    new object[]{ account1, new { email="joe.schmoe@newwork.com" } },
    new object[]{ account2, new { email="james.schmoe@newwork.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.

# Single mode
curl "https://api.placepay.com/invoices/kswxX5hFW57SN7icmdcaszd4" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X DELETE
# Single mode
invoice.delete()
# Single mode
invoice.delete()

<?php
# Single mode
$invoice->delete();
?>
// Single mode
invoice.delete()
// Single mode
invoice.delete()

Single mode

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

No request body


# Query mode
curl "https://api.placepay.com/invoices/?reference_id=example@example.com&query_mode=1" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X DELETE
# Query mode
invoices = place.Invoice.select(
    reference_id='example',
    delete_all=True
)
# Query mode
invoices = Place::Invoice.select(
    :reference_id => 'example',
    :delete_all => true
)
<?php
# Query mode
$invoices = Place\Invoice::select(array(
    'reference_id'=>'example',
    'delete_all'=>true
));
?>
// Query mode
place.Invoice.select({
    reference_id: 'example',
    delete_all: true
})
// Query mode
List<PlaceInvoices> invoices = PlaceInvoice.select(new {
    reference_id="example"
}, delete_all: true);

Query mode (See the query language)

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

No request body


# Bulk mode
curl "https://api.placepay.com/invoices/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X DELETE \
    -d [0][id]="rqlPhhU3aJ8DWBF5zPJI8HrU" \
    -d [1][id]="kswxX5hFW57SN7icmdcaszd4"
# Bulk mode
invoices = place.Invoice.delete_all([
    invoice1,
    invoice2
])
# Bulk mode
invoices = Place::Invoice.delete_all([
    invoice1,
    invoice2
])
<?php
# Bulk mode
$invoices = Place\Invoice::delete_all(array(
    account1,
    account2
));
?>
// Bulk mode
place.Invoice.delete_all([
    invoice1,
    invoice2
])
// Bulk mode
PlaceInvoice.delete_all(new[]{
    invoice1,
    invoice2
});

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.

# Single mode
curl "https://api.placepay.com/invoices/lEOCGQRFHXtZg51uBGHpyd7h" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
invoice = place.Invoice.get('lEOCGQRFHXtZg51uBGHpyd7h')
print invoice.json()
invoice = Place::Invoice.get('lEOCGQRFHXtZg51uBGHpyd7h')
puts invoice.json()
<?php
$invoice = Place\Invoice::get('lEOCGQRFHXtZg51uBGHpyd7h');
puts $invoice->json();
?>
place.Invoice.get('lEOCGQRFHXtZg51uBGHpyd7h')
    .then(function( invoice ){ console.log(invoice.json()) })
PlaceInvoice invoice = PlaceInvoice.get("lEOCGQRFHXtZg51uBGHpyd7h");
Console.WriteLine( invoice.json() )
{
  "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": "knowsnothing@gmail.com",
    "first_name": "Jon",
    "invoice_id": "16mgrY95eKG6oZ1hDx3kmBOkB",
    "last_name": "Snow",
    "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

# Example of using the `greater-than` operator
curl "https://api.placepay.com/transactions/?initiated_timestamp=>2017-11-01" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
# 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:
# Example of using the `greater-than` operator
curl "https://api.placepay.com/transactions/?status=declined|canceled" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
# Example of using the `greater-than` operator
transactions = place.Transaction.select(
    initiated_timestamp='>2017-11-01'
)
# Example of combining the `greater-than`, `less-than`, and `and` operator
transactions = place.Transaction.select(
    initiated_timestamp=[ '>2017-11-01', '<2017-11-15' ]
)
# Example of using the `or` operator
transactions = place.Transaction.select(
    status='declined|canceled'
)
# Example of using the `greater-than` operator
transactions = Place::Transaction.select(
    :initiated_timestamp => '>2017-11-01'
)
# Example of combining the `greater-than`, `less-than`, and `and` operator
transactions = Place::Transaction.select(
    :initiated_timestamp => [ '>2017-11-01', '<2017-11-15' ]
)
# Example of using the `or` operator
transactions = Place::Transaction.select(
    :status => 'declined|canceled'
)
<?php
# Example of using the `greater-than` operator
$transactions = Place\Transaction::select(array(
    'initiated_timestamp' => '>2017-11-01'
));
?>
<?php
# Example of combining the `greater-than`, `less-than`, and `and` operator
$transactions = Place\Transaction::select(array(
    'initiated_timestamp' => array( '>2017-11-01', '<2017-11-15' )
));
?>
<?php
# Example of using the `or` operator
$transactions = Place\Transaction::select(array(
    'status' => 'declined|canceled'
))
?>
// Example of using the `greater-than` operator
place.Transaction.select({
    initiated_timestamp: '>2017-11-01'
}).then(function( transactions ){})
// Example of combining the `greater-than`, `less-than`, and `and` operator
place.Transaction.select({
    initiated_timestamp: [ '>2017-11-01', '<2017-11-15' ]
}).then(function( transactions ){})
// Example of using the `or` operator
place.Transaction.select({
    status: 'declined|canceled'
}).then(function( transactions ){})
// Example of using the `greater-than` operator
List<PlaceTransaction> transactions = PlaceTransaction.select(new {
    initiated_timestamp=">2017-11-01"
})
// Example of combining the `greater-than`, `less-than`, and `and` operator
List<PlaceTransaction> transactions = PlaceTransaction.select(new {
    initiated_timestamp=new[]{ ">2017-11-01", "<2017-11-15" }
})
// Example of using the `or` operator
List<PlaceTransaction> transactions = PlaceTransaction.select(new {
    status="declined|canceled"
})
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

# Example of using the special range fields
curl "https://api.placepay.com/transactions/?limit=5&offset=100" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
# Example of using the special range fields
transactions = place.Transaction.select(
    limit=10,
    offset=5
)
# Example of using the special range fields
transactions = Place::Transaction.select(
    :limit => 10,
    :offset => 5
)
<?php
# Example of using the special range fields
$transactions = Place\Transaction::select(array(
    'limit' => 10,
    'offset' => 5
));
?>
// Example of using the special range fields
place.Transaction.select({
    limit: 10,
    offset: 5
}).then(function(transactions){})
// Example of using the special range fields
List<PlaceTransaction> transactions = PlaceTransaction.select(new {
    limit=10,
    offset=5
})
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

# Example of setting field preference globally
place.Transaction.default_params = { 'fields': '*,payer_conv_fee' }
# Example of setting field preference globally
Place::Transaction.default_params = { fields: '*,payer_conv_fee' }
<?php
# Example of setting field preference globally
Place\Transaction::default_params = array( 'fields' => '*,payer_conv_fee' );
?>
// Example of setting field preference globally
place.Transaction.default_params = { 'fields': '*,payer_conv_fee' }
// Example of setting field preference globally
PlaceTransaction.default_params = new { fields='*,payer_conv_fee' }

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

curl "https://api.placepay.com/transactions/3axWdCgzecx9HR7PSOqP2" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT
    -d "custom_fields[custom]=data"
trans = place.Transaction.get( '3axWdCgzecx9HR7PSOqP2',
    fields='*,custom_fields' )

trans.update(custom_fields={'custom': 'data'},
    fields: '*,custom_fields')
trans = Place::Transaction.get( '3axWdCgzecx9HR7PSOqP2',
    fields: '*,custom_fields' )

trans.update(custom_fields: {'custom': 'data'},
    fields: '*,custom_fields')
<?php
$trans = Place\Transaction.get('3axWdCgzecx9HR7PSOqP2',
    array( "fields"=>"*,custom_fields" ))

$trans.update(array("custom_fields"=>{"custom": "data"},
    "fields"=>"*,custom_fields"))
?>
place.Transaction.get('3axWdCgzecx9HR7PSOqP2',
    {fields: '*,custom_fields'})
    .then(function(trans) {
        trans.update({
            custom_fields: {'custom': 'data'},
            fields: '*,custom_fields'
        })
    })
PlaceTransaction trans = PlaceTransaction.get( "3axWdCgzecx9HR7PSOqP2",
    new { fields="*,custom_fields" } )

trans.update(new { custom_fields=new { custom="data" } },
    new { fields="*,custom_fields" })
{
  "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

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

{
    "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 Place 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

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"
trans = place.Transaction.select( initiated_timestamp='>2018-05-01',
    fields='sum(amount),status', group_by='status' )
trans = Place::Transaction.select( initiated_timestamp: '>2018-05-01',
    fields: 'sum(amount),status', group_by: 'status' )
<?php
$trans = Place\Transaction.select(array( "initiated_timestamp"=>">2018-05-01",
    "fields"=>"*,custom_fields" ))
?>
place.Transaction.select({ initiated_timestamp: '>2018-05-01',
    fields: 'sum(amount),status', group_by: 'status'})
    .then(function(trans) {
    })
PlaceTransaction trans = PlaceTransaction.select(new { initiated_timestamp=">2018-05-01",
    fields="sum(amount),status", group_by="status" })
[
  {
    "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

<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 Place Pay plugin. This will embed a Place 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.

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

place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

rs_transaction_id = '19QsDurdSxJ0gVNzOcQSlew3D'

place.Transaction.select(
    id=rs_transaction_id,
    update_all={ 'status': 'complete' }
)
require 'place'
Place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

post '/submit_payment/' do
    rs_transaction_id = params[:rs_transaction_id]

    transaction = Place::Transaction.get(
        rs_transaction_id,
        :update => { 'status' => 'complete' }
    )
end
<?php
Place\Place::$api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd';

$rs_transaction_id = $_GET['rs_transaction_id'];

$transaction = Place\Transaction::get(
    rs_transaction_id,
    array( 'status' => 'complete' ) #get object and update status in single request
);
?>
var place = require('place')

place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

rs_transaction_id = '19QsDurdSxJ0gVNzOcQSlew3D'

place.Transaction.select({
    id: rs_transaction_id,
    update_all: { 'status': 'complete' }
})
PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

string rs_transaction_id = "19QsDurdSxJ0gVNzOcQSlew3D";

PlaceTransaction.select(new {
    id=rs_transaction_id
}, update_all: new { 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

<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

<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

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

# Create a payer account
curl "https://api.placepay.com/accounts/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d email="joe.schmoe@example.com" \
    -d full_name="Joe Schmoe" \
    -d user_type="payer"
# Create a payer account
account = place.Account.create(
    email='joe.schmoe@example.com',
    full_name='Joe Schmoe',
    user_type='payer'
)
# At this point store the account.id for use later
# Create a payer account
account = Place::Account.create(
    :email => 'joe.schmoe@example.com',
    :full_name => 'Joe Schmoe',
    :user_type => 'payer'
)
# At this point store the account.id for use later
<?php
# Create a payer account
$account = Place\Account::create(array(
    'email' => 'joe.schmoe@example.com',
    'full_name' => 'Joe Schmoe',
    'user_type' => 'payer'
));
# At this point store the $account->id for use later
?>
// Create a payer account
place.Account.create({
    email: 'joe.schmoe@example.com',
    full_name: 'Joe Schmoe',
    user_type: 'payer'
}).then(function(account){
    // At this point store the account.id for use later
})
// Create a payer account
PlaceAccount account = PlaceAccount.create(new {
    email="joe.schmoe@example.com",
    full_name="Joe Schmoe",
    user_type="payer"
});
// At this point store the account.id for use later

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


Creating a session access token for the Pay plugin

# 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
# Create an access token
access_token = place.AccessToken.create(
    account_id=account.id,
    type='session_access'
)
# Use the value of access_token.acess_token
# as the data-access-token param with the plugin
# Create an access token
access_token = Place::AccessToken.create(
    :account_id => account.id,
    :type => 'session_access'
)
# Use the value of access_token.acess_token
# as the data-access-token param with the plugin
<?php
# Create an access token
$access_token = Place\AccessToken::create(array(
    'account_id' => $account->id,
    'type' => 'session_access'
));
# Use the value of $access_token->acess_token
# as the data-access-token param with the plugin
?>
// Create an access token
place.AccessToken.create({
    account_id: account.id,
    type: 'session_access'
}).then(function(access_token) {
    // Use the value of access_token.acess_token
    // as the data-access-token param with the plugin
})
// Create an access token
PlaceAccessToken access_token = PlaceAccessToken.create(new {
    account_id=account.id,
    type="session_access"
});
// Use the value of access_token.acess_token
// as the data-access-token param with the plugin

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

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

# Create a payer account
curl "https://api.placepay.com/accounts/?fields=*,username,access_tokens" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d email="joe.schmoe@example.com" \
    -d full_name="Joe Schmoe" \
    -d user_type="payer" \
    -d access_tokens[0][type]='session_access'
# Create a payer account
account = place.Account.create(
    username='your_unique_id',
    email='joe.schmoe@example.com',
    full_name='Joe Schmoe',
    user_type='payer',
    access_tokens=[
        place.AccessToken( type='session_access' )
    ],
    fields='*,username,access_tokens'
)
# At this point, just use the account.access_tokens[0].access_token for the *Pay* plugin
# Create a payer account
account = Place::Account.create(
    :username => 'your_unique_id',
    :email => 'joe.schmoe@example.com',
    :full_name => 'Joe Schmoe',
    :user_type => 'payer',
    :access_tokens => [
        place.AccessToken.new( :type => 'session_access' )
    ],
    :fields => '*,username,access_tokens'
)
# At this point, just use the account.access_tokens[0].access_token for the *Pay* plugin
<?php
# Create a payer account
$account = Place\Account::create(array(
    'username' => 'your_unique_id',
    'email' => 'joe.schmoe@example.com',
    'full_name' => 'Joe Schmoe',
    'user_type' => 'payer',
    'access_tokens' => array(
        new Place\AccessToken( 'type' => 'session_access' )
    )
));
#  At this point, just use the $account->access_tokens[0]->access_token for the *Pay* plugin
?>
// Create a payer account
place.Account.create({
    username: 'your_unique_id',
    email: 'joe.schmoe@example.com',
    full_name: 'Joe Schmoe',
    user_type: 'payer',
    access_tokens: [
        place.AccessToken({ type: 'session_access' })
    ],
    fields: '*,username,access_tokens'
}).then(function(account){
    // At this point, just use the account.access_tokens[0].access_token for the *Pay* plugin
})

// Create a payer account
PlaceAccount account = PlaceAccount.create(new {
    username="your_unique_id",
    email="joe.schmoe@example.com",
    full_name="Joe Schmoe",
    user_type="payer",
    access_tokens=new[]{
        new PlaceAccessToken(){ type="session_access" }
    }
}, new { fields="*,username,access_tokens" });
// At this point, just use the account.access_tokens[0].access_token for the *Pay* plugin

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

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

curl "https://api.placepay.com/autopay_enrollments" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
autopay_enrollments = place.AutopayEnrollments.select()
autopay_enrollments = Place::AutopayEnrollments.select()
<?php
$autopay_enrollments = Place\AutopayEnrollments::select();
?>
place.AutopayEnrollments.select()
    .then(function(autopay_enrollments){})
PlaceAutopayEnrollments autopay_enrollments = PlaceAutopayEnrollments.select()

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

payments = []
for enrollment in autopay_enrollments:
    payments.append( place.Transaction(
        type='charge',
        amount=1000, # replace this with the outstanding balance
        description='March Rent',
        payment_method_id=enrollment.payment_method_id,
        deposit_account_id=enrollment.deposit_account_id
    ) )
payments = []
for enrollment in autopay_enrollments
    payments.push( Place::Transaction.new(
        :type => 'charge',
        :amount => 1000, # replace this with the outstanding balance
        :description => 'March Rent',
        :payment_method_id => enrollment.payment_method_id,
        :deposit_account_id => enrollment.deposit_account_id
    ) )
end
<?php
$payments = array();
foreach( $autopay_enrollments as $enrollment ) {
    $payments.push( new Place\Transaction(array(
        'type' => 'charge',
        'amount' => 1000, # replace this with the outstanding balance
        'description' => 'March Rent',
        'payment_method_id' => $enrollment->payment_method_id,
        'deposit_account_id' => $enrollment->deposit_account_id
    )) )
}
?>
payments = []
for ( var i = 0; i < autopay_enrollments.length; i++ ) {
    var enrollment = autopay_enrollments[i]
    payments.push( place.Transaction({
        type: 'charge',
        amount: 1000, // replace this with the outstanding balance
        description: 'March Rent',
        payment_method_id: enrollment.payment_method_id,
        deposit_account_id: enrollment.deposit_account_id
    }) )
}
List<PlaceTransaction> payments = new List<PlaceTransaction>();
for ( int i=0; i < autopay_enrollments.Count; i++ ) {
    PlaceAutopayEnrollments enrollment = autopay_enrollments[i];
    payments.Add( new PlaceTransaction(){
        type="charge",
        amount=1000, // replace this with the outstanding balance
        description="March Rent",
        payment_method_id=enrollment.payment_method_id,
        deposit_account_id=enrollment.deposit_account_id
    } );
}

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

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"
# process automatic payments
payments = place.Transaction.create( payments )

for payment in payments:
    if payment.status == 'complete':
        # handle complete payment
    else:
        # handle declined payment
# process automatic payments
payments = Place::Transaction.create( payments )

for payment in payments
    if payment.status == 'complete'
        # handle complete payment
    else
        # handle declined payment
    end
end
<?php
# process automatic payments
$payments = Place\Transaction:create( $payments )

foreach( $payments as $payment ) {
    if ( $payment->status == 'complete' ) {
        # handle complete payment
    } else {
        # handle declined payment
    }
}
?>
// process automatic payments
place.Transaction.create( payments )
    .then(function(payments) {
        for ( var i = 0; i < payments.length; i++ ) {
            var payment = payments[i]
            if ( payment.status == 'complete' )
                // handle complete payment
            else
                // handle declined payment
        }
    })
// process automatic payments
PlaceTransaction payments = PlaceTransaction.create( payments )

for ( int i=0; i < payments.Count; i++ ) {
    PlaceTransaction payment = payments[i];
    if ( payment.status == "complete" )
        // handle complete payment
    else
        // handle declined payment
}

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

<script>
Place.pay.on( '.mybutton', 'loaded', function() {
    console.log('event captured')
})
</script>
<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

<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

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

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

<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

# 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"
# Create a recipient account
deposit_account = place.DepositAccount.create(
    company='Example Landlord LLC',
    phone='111-222-3333',
    address=place.Address(
        street_address='123 Example St',
        unit_number='#4',
        city_state_zip='New York, NY 10004'
    )
)
# At this point store the deposit_account.id for use later
# Create a recipient account
deposit_account = Place::DepositAccount.create(
    :company => 'Example Landlord LLC',
    :phone => '111-222-3333',
    :address => Place::Address.new(
        :street_address => '123 Example St',
        :unit_number => '#4',
        :city_state_zip => 'New York, NY 10004'
    )
)
# At this point store the deposit_account.id for use later
<?php
# Create a recipient account
$deposit_account = new Place\DepositAccount::create(array(
    'company' => 'Example Landlord LLC',
    'phone' => '111-222-3333',
    'address' => new Place\Address(
        'street_address' => '123 Example St',
        'unit_number' => '#4',
        'city_state_zip' => 'New York, NY 10004'
    )
))
# At this point store the $deposit_account.id for use later
?>
// Create a recipient account
place.DepositAccount.create({
    company: 'Example Landlord LLC',
    phone: '111-222-3333',
    address: place.Address({
        street_address: '123 Example St',
        unit_number: '#4',
        city_state_zip: 'New York, NY 10004'
    })
}).then(function(deposit_account){
    // At this point store the deposit_account.id for use later
})
// Create a recipient account
PlaceDepositAccount deposit_account = PlaceDepositAccount.create(new {
    company="Example Landlord LLC",
    phone="111-222-3333",
    address=new PlaceAddress(){
        street_address="123 Example St",
        unit_number="#4",
        city_state_zip="New York, NY 10004"
    }
})
// At this point store the deposit_account.id for use later

First you need to create a deposit account.


Load the Deposit Button

# Create an access token
curl "https://api.placepay.com/access_tokens" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d type=session_access
# Create an access token
access_token = place.AccountToken.create(
    type='session_access'
)
# Use the value of access_token.acess_token
# as the data-access-token param with the plugin
# Create an access token
access_token = Place::AccountToken.create(
    :type => 'session_access'
)
# Use the value of access_token.acess_token
# as the data-access-token param with the plugin
<?
    # Create an access token
    $access_token = Place\AccountToken::create(array(
        'type' => 'session_access'
    ))
    # Use the value of access_token.acess_token
    # as the data-access-token param with the plugin
?>
// Create an access token
place.AccountToken.create(
    type='session_access'
).then(function(access_token){
    // Use the value of acess_token.acess_token
    // as the data-access-token param with the plugin
})
// Create an access token
PlaceAccountToken access_token = PlaceAccountToken.create(new {
    type="session_access"
});
// Use the value of access_token.acess_token
// as the data-access-token param with the plugin
<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

<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

# 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
# Get the processing activation status
deposit_account = place.DepositAccount.get('hzus4iw9ujkR9TPcpYEs')

print deposit_account.deposit_method.processing_activation_status
# returns either 'pending', 'in_review', 'active', 'inactive', 'action_needed'
# Get the processing activation status
deposit_account = Place::DepositAccount.get('hzus4iw9ujkR9TPcpYEs')

puts deposit_account.deposit_method.processing_activation_status
# returns either 'pending', 'in_review', 'active', 'inactive', 'action_needed'
<?
    # Get the processing activation status
    $deposit_account = Place\DepositAccount::get('hzus4iw9ujkR9TPcpYEs');

    echo(deposit_account->deposit_method->processing_activation_status);
    # returns either 'pending', 'in_review', 'active', 'inactive', 'action_needed'
?>
// Get the processing activation status
place.DepositAccount.get('hzus4iw9ujkR9TPcpYEs')
    .then(function(deposit_account){
        console.log(deposit_account.deposit_method.processing_activation_status)
        // returns either 'pending', 'in_review', 'active', 'inactive', 'action_needed'
    })
// Get the processing activation status
PlaceDepositAccount deposit_account = PlaceDepositAccount.get('hzus4iw9ujkR9TPcpYEs');

Console.Log(deposit_account.deposit_method.processing_activation_status);
// Use the value of access_token.acess_token
// returns either 'pending', 'in_review', 'active', 'inactive', 'action_needed'

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

curl "https://api.placepay.com/transactions" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d "fields=*,credit_ledger" \
    -d "type=deposit" \
    -d "account_id=$deposit_account_id"
trans = place.Transaction.select( type='deposit',
    account_id=deposit_account.id, fields='*,credit_ledger' )
trans = Place::Transaction.select( type: 'deposit',
    account_id: deposit_account.id, fields: '*,credit_ledger' )
trans = Place\Transaction::select(array(
    'type'=>'deposit',
    'account_id'=>$deposit_account->id,
    'fields'=>'*,credit_ledger'
))
place.Transaction.select({
    'type': 'deposit',
    'account_id': deposit_account.id,
    'fields': '*,credit_ledger'
)).then(function(trans) {
})
PlaceTransaction trans = PlaceTransaction.select(new{
    account_id=deposit_account.id,
    type="deposit",
    fields="*,credit_ledger"
});

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

curl "https://api.placepay.com/transactions" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d "fields=*,debit_ledger"
trans = place.Transaction.select( type='charge',
    account_id=account.id, fields='*,debit_ledger' )
trans = Place::Transaction.select( type: 'charge',
    account_id: account.id, fields: '*,debit_ledger' )
trans = Place\Transaction::select(array(
    'type'=>'charge',
    'account_id'=>$account->id,
    'field'=>'*,debit_ledger'
))
place.Transaction.select({
    'type': 'charge',
    'account_id': account.id,
    'fields': '*,debit_ledger'
)).then(function(trans) {
})
PlaceTransaction trans = PlaceTransaction.select(new{
    type="charge",
    account_id=deposit_account.id,
    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.

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

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"
params = {
    'fields[self]': '*,credit_ledger',
    'fields[credit_ledger][self]': '*,source'
}

trans = place.Transaction.select( type='deposit',
    account_id=deposit_account.id, **params )
params = {
    'fields[self]': '*,credit_ledger',
    'fields[credit_ledger][self]': '*,source'
}

trans = Place::Transaction.select( type: 'deposit',
    account_id: deposit_account.id, **params )
trans = Place\Transaction::select(array(
    'type'=>'deposit',
    'account_id'=>$deposit_account->id,
    'fields[self]'=>'*,credit_ledger',
    'fields[credit_ledger][self]'=>'*,source'
))
place.Transaction.select({
    'type': 'deposit',
    'account_id': deposit_account.id,
    'fields[self]': '*,credit_ledger',
    'fields[credit_ledger][self]': '*,source'
)).then(function(trans) {
})
Dictionary<string, string> parameters = new Dictionary<string, string>{
    { "fields[self]", "*,credit_ledger" },
    { "fields[credit_ledger][self]", "*,source" },
    { "type", "deposit" },
    { "account_id", deposit_account.id }
};

PlaceTransaction trans = PlaceTransaction.select(parameters);

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

curl "https://api.placepay.com/transactions/14qmPCuDo9lY1TI82kpLM6cKo" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT \
    -d "status=canceled"
payment = place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')
payment.update(status='canceled')
payment = Place::Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')
payment.update(status: 'canceled')
<?php
$payment = Place\Transaction::get('14qmPCuDo9lY1TI82kpLM6cKo');
$payment->update(array( 'status' => 'canceled' ))
?>
place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')
    .then(function(payment){
        return payment.update({ status: 'canceled' })
    })
PlaceTransaction payment = PlaceTransaction.get("14qmPCuDo9lY1TI82kpLM6cKo");
payment.update(new { 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

curl "https://api.placepay.com/transactions/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d "type=refund" \
    -d "amount=1000" \
    -d "credit_ledger[0][source_id]=14qmPCuDo9lY1TI82kpLM6cKo"
payment = place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')

refund = place.Transaction.create(
    amount=payment.amount,
    type='refund',
    credit_ledger=[{
        'source_id': payment.id
    }]
)
payment = Place::Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')

refund = Place::Transaction.create(
    :amount => payment.amount,
    :type => 'refund',
    :credit_ledger => [{
        'source_id' => payment.id
    }]
)
<?php
$payment = Place\Transaction::get('14qmPCuDo9lY1TI82kpLM6cKo');

$refund = Place\Transaction::create(array(
    'amount' => $payment->amount,
    'type' => 'refund',
    'credit_ledger' => array(array(
        'source_id' => $payment->id
    ))
));
?>
place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo')
    .then(function(payment){
        return place.Transaction.create({
            amount: payment.amount,
            type: 'refund',
            credit_ledger: [{
                'source_id': payment.id
            }]
        })
    })
PlaceTransaction payment = PlaceTransaction.get("14qmPCuDo9lY1TI82kpLM6cKo");

PlaceTransaction refund = PlaceTransaction.create(new {
    amoun=payment.amount,
    type="refund",
    credit_ledger=new[]{
        new PlaceTransactionLedger(){ source_id=payment.id }
    }
});

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

# Example of using the `greater-than` operator
curl "https://api.placepay.com/transactions/?status=failed&failed_timestamp=>2017-11-01" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
failed_payments = place.Transaction.select(
    status='failed',
    failed_timestamp='>2017-11-01'
)

for payment in failed_payments:
    print payment.status_details
    # returns R01 - INSUFFICIENT FUNDS
failed_payments = Place::Transaction.select(
    :status => 'failed',
    :failed_timestamp => '>2017-11-01'
)

for payment in failed_payments
    puts payment.status_details
    # returns R01 - INSUFFICIENT FUNDS
end
<?php
$failed_payments = Place\Transaction::select(array(
    'status' => 'failed',
    'failed_timestamp' => '>2017-11-01'
))

foreach( $failed_payments as $payment ) {
    echo $payment->status_details;
    # returns R01 - INSUFFICIENT FUNDS
}
?>
place.Transaction.select({
    status: 'failed',
    failed_timestamp: '>2017-11-01'
}).then(function(failed_payments){
    for ( var i = 0; i < failed_payments.length; i++ ) {
        var payment = failed_payments[i]
        console.log( payment.status_details )
        // returns R01 - INSUFFICIENT FUNDS
    }
})
List<PlaceTransaction> failed_payments = PlaceTransaction.select(new {
    status="failed",
    failed_timestamp=">2017-11-01"
});

for ( int i=0; i < failed_payments.Count; i++ ) {
    PlaceTransaction payment = failed_payments[i];
    Console.WriteLine( payment.status_details );
    // returns R01 - INSUFFICIENT FUNDS
}

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

curl "https://api.placepay.com/transactions/?type=chargeback&initiated_timestamp=>2018-05-01&fields=*,credit_ledger" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
chargebacks = place.Transaction.select(
    type='chargeback',
    initiated_timestamp='>2018-05-01',
    fields='*,credit_ledger'
)

for payment in chargebacks:
    print payment.credit_ledger[0].source_id
    # returns original transaction id
chargebacks = Place::Transaction.select(
    type: 'chargeback',
    initiated_timestamp: '>2018-05-01',
    fields: '*,credit_ledger'
)

for payment in chargebacks
    puts payment.credit_ledger[0].source_id
    # returns original transaction id
end
<?php
$chargebacks = Place\Transaction::select(array(
    'type' => 'chargeback',
    'initiated_timestamp' => '>2018-05-01',
    'fields' => '*,credit_ledger'
))

foreach( $chargebacks as $payment ) {
    echo $payment->credit_ledger[0]->source_id;
    # returns original transaction id
}
?>
place.Transaction.select({
    type: 'chargeback',
    initiated_timestamp: '>2018-05-01',
    fields: '*,credit_ledger'
}).then(function(chargebacks){
    for ( var i = 0; i < chargebacks.length; i++ ) {
        var payment = chargebacks[i]
        console.log( payment.credit_ledger[0].id )
        // returns original transaction id
    }
})

List<PlaceTransaction> chargebacks = PlaceTransaction.select(new {
    type="chargeback",
    initiated_timestamp=">2018-05-01",
    fields="*,credit_ledger"
});

for ( int i=0; i < chargebacks.Count; i++ ) {
    PlaceTransaction payment = chargebacks[i];
    Console.WriteLine( payment.credit_ledger[0].source_id );
    // returns original transaction id
}

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

curl "https://api.placepay.com/transactions/14qmPCuDo9lY1TI82kpLM6cKo?field=*,payer_conv_fee" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
payment = place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo',
    fields='*,payer_conv_fee')

print payment.fee # Fee charged to the recipient
print payment.payer_conv_fee # Fee charged to the payer
payment = Place::Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo',
    fields: '*,payer_conv_fee')

puts payment.fee # Fee charged to the recipient
puts payment.payer_conv_fee # Fee charged to the payer
<?php
$payment = Place\Transaction::get('14qmPCuDo9lY1TI82kpLM6cKo');

echo $payment->fee; # Fee charged to the recipient
echo "\n";
echo $payment->payer_conv_fee; # Fee charged to the payer
echo "\n";
?>
place.Transaction.get('14qmPCuDo9lY1TI82kpLM6cKo',{ fields: '*,payer_conv_fee'})
    .then(function(payment){
        console.log(payment.fee) // Fee charged to the recipient
        console.log(payment.payer_conv_fee) // Fee charged to the payer
    })
PlaceTransaction payment = PlaceTransaction.get("14qmPCuDo9lY1TI82kpLM6cKo",
    new { fields="*,payer_conv_fee" });

Console.WriteLine( payment.fee ); // Fee charged to the recipient
Console.WriteLine( payment.payer_conv_fee ); // Fee charged to the payer

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

curl "https://api.placepay.com/events/" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -d "callback_url=https://example.com/ach_failure_handler" \
    -d "event=ach_failure"
place.Event.create(
  callback_url = 'https://example.com/ach_failure_handler',
  event = 'ach_failure'
)
Place::Event.create(
  callback_url: "https://example.com/ach_failure_handler",
  event: "ach_failure"
)
<?php
Place\Event::create(array(
  "callback_url"=>"https://example.com/ach_failure_handler",
  "event"=>"ach_failure"
))
?>
place.Event.create({
  callback_url: 'https://example.com/ach_failure_handler',
  event: 'ach_failure'
})
PlaceEvent.create(new {
  callback_url="https://example.com/ach_failure_handler",
  event="ach_failure"
});

Event Example

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

# 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
# Create a recurring invoice
recurring_invoice = place.RecurringInvoice.create(
    start_date='2017-01-01',
    end_date='2017-12-31',
    recurring_frequency='monthly',
    invoice_template=place.Invoice(
        type='rent',
        deposit_account_id = 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        items=[
            place.InvoiceItem(
                type='rent',
                amount=1000
            ),
            place.InvoiceItem(
                type='ammenity',
                amount=50,
                date_incurred='2017-02-15'
            )
        ],
        payers=[
            place.InvoicePayer(
                account_id=account_id
            )
        ]
    )
)
# Create a recurring invoice
recurring_invoice = Place::RecurringInvoice.create(
    :start_date => '2017-01-01',
    :end_date => '2017-12-31',
    :recurring_frequency => 'monthly',
    :invoice_template => Place::Invoice.new(
        :type => 'rent',
        :deposit_account_id => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        :items => [
            Place::InvoiceItem.new(
                :type => 'rent',
                :amount => 1000
            ),
            Place::InvoiceItem.new(
                :type => 'ammenity',
                :amount => 50,
                :date_incurred => '2017-02-15'
            )
        ],
        :payers => [
            Place::InvoicePayer.new(
                :account_id => account_id
            )
        ]
    )
)
<?php
# Create a recurring invoice
$recurring_invoice = Place\RecurringInvoice::create(array(
    'start_date' => '2017-01-01',
    'end_date' => '2017-12-31',
    'recurring_frequency' => 'monthly',
    'invoice_template' => Place::Invoice.new(
        'type' => 'rent',
        'deposit_account_id' => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        'items' => array(
            new Place\InvoiceItem(array(
                'type' => 'rent',
                'amount' => 1000
            )),
            new Place\InvoiceItem(array(
                'type' => 'ammenity',
                'amount' => 50,
                'date_incurred' => '2017-02-15'
            ))
        ),
        'payers' => array(
            new Place\InvoicePayer(array(
                'account_id' => $account_id
            ))
        )
    )
));
?>
// Create a recurring invoice
place.RecurringInvoice.create({
    start_date: '2017-01-01',
    end_date: '2017-12-31',
    recurring_frequency: 'monthly',
    invoice_template: place.Invoice(
        type: 'rent',
        deposit_account_id :  'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        items: [
            place.InvoiceItem(
                type: 'rent',
                amount: 1000
            ),
            place.InvoiceItem(
                type: 'ammenity',
                amount: 50,
                date_incurred: '2017-02-15'
            )
        ],
        payers: [
            place.InvoicePayer(
                account_id: account_id
            )
        ]
    )
})
// Create a recurring invoice
PlaceRecurringInvoice recurring_invoice = PlaceRecurringInvoice.create(new {
    start_date="2017-01-01",
    end_date="2017-12-31",
    recurring_frequency="monthly",
    invoice_template=new PlaceInvoice(){
        type="rent",
        deposit_account_id="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA",
        items=new[]{
            new PlaceInvoiceItem(){
                type="rent",
                amount=1000
            },
            new PlaceInvoiceItem(){
                type="ammenity",
                amount=50,
                date_incurred="2017-02-15"
            }
        },
        payers=new[]{
            new PlaceInvoicePayer(){
                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.


# 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
# Create a one-time invoice
invoice = place.Invoice.create(
    type='rent',
    deposit_account_id = 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    items=[
        place.InvoiceItem(
            type='one_time_fee',
            amount=1000
        )
    ],
    payers=[
        place.InvoicePayer(
            account_id=account_id
        )
    ]
)
# Create a one-time invoice
invoice = Place::Invoice.create(
    :type => 'rent',
    :deposit_account_id => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    :items => [
        Place::InvoiceItem.new(
            :type => 'one_time_fee',
            :amount => 1000
        )
    ],
    :payers => [
        Place::InvoicePayer.new(
            :account_id => account_id
        )
    ]
)
<?php
# Create a one-time invoice
invoice = Place\Invoice::create(array(
    'type' => 'rent',
    'deposit_account_id' => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    'items' => array(
        new Place\InvoiceItem(array(
            'type' => 'one_time_fee',
            'amount' => 1000
        ))
    ),
    'payers' => array(
        new Place\InvoicePayer(array(
            'account_id' => $account_id
        ))
    )
));
?>
// Create a one-time invoice
place.Invoice.create({
    type: 'rent',
    deposit_account_id :  'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    items: [
        place.InvoiceItem(
            type: 'one_time_fee',
            amount: 1000
        )
    ],
    payers: [
        place.InvoicePayer(
            account_id: account_id
        )
    ]
})
// Create a one-time invoice
PlaceInvoice invoice = PlaceInvoice.create(new {
    type="rent",
    deposit_account_id="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA",
    items=new[]{
        new PlaceInvoiceItem(){
            type="one_time_fee",
            amount=1000
        }
    },
    payers=new[]{
        new PlaceInvoicePayer(){
            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


# 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
# Create a one-time invoice
invoice = place.Invoice.create(
    type='rent',
    deposit_account_id = 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    items=[
        place.InvoiceItem(
            type='one_time_fee',
            amount=1000,
            allocations=[
                place.InvoiceItemAllocation(
                    account_id=account1_id,
                    amount=600
                ),
                place.InvoiceItemAllocation(
                    account_id=account2_id,
                    amount=400
                ),
            ]
        )
    ],
    payers=[
        place.InvoicePayer(
            account_id=account1_id
        ),
        place.InvoicePayer(
            account_id=account2_id
        )
    ]
)
# Create a multi-payer invoice
invoice = Place::Invoice.create(
    :type => 'rent',
    :deposit_account_id => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    :items => [
        Place::InvoiceItem.new(
            :type => 'one_time_fee',
            :amount => 1000,
            :allocations => [
                Place::InvoiceItemAllocation.new(
                    :account_id => account1_id,
                    :amount => 600
                ),
                Place::InvoiceItemAllocation.new(
                    :account_id => account2_id,
                    :amount => 400
                )
            ]
        )
    ],
    :payers => [
        Place::InvoicePayer.new(
            :account_id => account1_id
        ),
        Place::InvoicePayer.new(
            :account_id => account2_id
        )
    ]
)
<?php
# Create a multi-payer invoice
$invoice = Place\Invoice::create(array(
    'type' => 'rent',
    'deposit_account_id' => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    'items' => array(
        new Place\InvoiceItem(array(
            'type' => 'one_time_fee',
            'amount' => 1000,
            'allocations' => array(
                new Place\InvoiceItemAllocation(
                    'account_id' => $account1_id,
                    'amount' => 600
                ),
                new Place\InvoiceItemAllocation(
                    'account_id' => $account2_id,
                    'amount' => 400
                )
            )
        ))
    ),
    'payers' => array(
        new Place\InvoicePayer(
            'account_id' => $account1_id
        ),
        new Place\InvoicePayer(
            'account_id' => $account2_id
        )
    )
));
?>
// Create a one-time invoice
place.Invoice.create({
    type: 'rent',
    deposit_account_id :  'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
    items: [
        place.InvoiceItem(
            type: 'one_time_fee',
            amount: 1000,
            allocations: [
                place.InvoiceItemAllocation(
                    account_id: account1_id,
                    amount: 600
                ),
                place.InvoiceItemAllocation(
                    account_id: account2_id,
                    amount: 400
                ),
            ]
        )
    ],
    payers: [
        place.InvoicePayer(
            account_id: account1_id
        ),
        place.InvoicePayer(
            account_id: account2_id
        )
    ]
})
// Create a one-time invoice
PlaceInvoice invoice = PlaceInvoice.create(new {
    type="rent",
    deposit_account_id="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA",
    items=new[]{
        new PlaceInvoiceItem(){
            type="one_time_fee",
            amount=1000,
            allocations=new[]{
                new PlaceInvoiceItemAllocation(){
                    account_id=account1_id,
                    amount=600
                },
                new PlaceInvoiceItemAllocation(){
                    account_id=account2_id,
                    amount=400
                }
            }
        }
    },
    payers=new[]{
        new PlaceInvoicePayer(){
            account_id=account1_id
        },
        new PlaceInvoicePayer(){
            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.


# 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
# Create a prorated recurring invoice
recurring_invoice = place.RecurringInvoice.create(
    start_date='2018-01-15',
    end_date='2018-12-31',
    recurring_frequency='monthly',
    prorated=True,
    invoice_template=place.Invoice(
        type='rent',
        deposit_account_id = 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        items=[
            place.InvoiceItem(
                type='rent',
                amount=1000
            ),
            place.InvoiceItem(
                type='ammenity',
                amount=50,
                date_incurred='2017-02-20'
            )
        ],
        payers=[
            place.InvoicePayer(
                account_id=account_id
            )
        ]
    )
)
# Create a prorated recurring invoice
recurring_invoice = Place::RecurringInvoice.create(
    :start_date => '2018-01-15',
    :end_date => '2018-12-31',
    :recurring_frequency => 'monthly',
    :prorated => true,
    :invoice_template => Place::Invoice.new(
        :type => 'rent',
        :deposit_account_id => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        :items => [
            Place::InvoiceItem.new(
                :type => 'rent',
                :amount => 1000
            ),
            Place::InvoiceItem.new(
                :type => 'ammenity',
                :amount => 50,
                :date_incurred => '2017-02-20'
            )
        ],
        :payers => [
            Place::InvoicePayer.new(
                :account_id => account_id
            )
        ]
    )
)
<?php
# Create a prorated recurring invoice
$recurring_invoice = Place\RecurringInvoice::create(array(
    'start_date' => '2018-01-15',
    'end_date' => '2018-12-31',
    'recurring_frequency' => 'monthly',
    'prorated' => true,
    'invoice_template' => new Place\Invoice(array(
        'type' => 'rent',
        'deposit_account_id' => 'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        'items' => array(
            new Place\InvoiceItem(array(
                'type' => 'rent',
                'amount' => 1000
            )),
            new Place\InvoiceItem(array(
                'type' => 'ammenity',
                'amount' => 50,
                'date_incurred' => '2017-02-20'
            ))
        ),
        'payers' => array(
            new Place\InvoicePayer(array(
                'account_id' => $account_id
            ))
        )
    ))
));
?>
// Create a prorated recurring invoice
place.RecurringInvoice.create({
    start_date: '2018-01-15',
    end_date: '2018-12-31',
    recurring_frequency: 'monthly',
    prorated: true,
    invoice_template: place.Invoice(
        type: 'rent',
        deposit_account_id :  'AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA',
        items: [
            place.InvoiceItem(
                type: 'rent',
                amount: 1000
            ),
            place.InvoiceItem(
                type: 'ammenity',
                amount: 50,
                date_incurred: '2017-02-20'
            )
        ],
        payers: [
            place.InvoicePayer(
                account_id: account_id
            )
        ]
    )
})
// Create a prorated recurring invoice
PlaceRecurringInvoice recurring_invoice = PlaceRecurringInvoice.create(new {
    start_date="2018-01-15",
    end_date="2018-12-31",
    recurring_frequency="monthly",
    prorated=true,
    invoice_template=new PlaceInvoice(){
        type="rent",
        deposit_account_id="AcOnw5PigJ4Ww43FoBx54oChPOKAkztmTQA",
        items=new[]{
            new PlaceInvoiceItem(){
                type="rent",
                amount=1000
            },
            new PlaceInvoiceItem(){
                type="ammenity",
                amount=50,
                date_incurred="2017-02-20"
            }
        },
        payers=new[]{
            new PlaceInvoicePayer(){
                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.

# 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"
invoice = place.Invoice.get('1QbV4MOnHKH9GeKeb')

if not invoice.paid:
    trans = place.Transaction.create(
        account_id=invoice.payers[0].account_id,
        amount=invoice.amount_allocated,
        type='charge',
        invoice_payer_allocations=[
            place.TransactionAllocation(
                amount=invoice.amount_allocated,
                invoice_payer_id=invoice.payers[0].id
            )
        ],
        fields='*,invoice_payer_allocations'
    )
    print trans.json()
invoice = Place::Invoice.get('1QbV4MOnHKH9GeKeb')

if !invoice.paid
    trans = Place::Transaction.create(
        account_id: invoice.payers[0].account_id,
        amount: invoice.amount_allocated,
        type: 'charge',
        invoice_payer_allocations: [
            Place::TransactionAllocation.new(
                amount: invoice.amount_allocated,
                invoice_payer_id: invoice.payers[0].id
            )
        ],
        fields: '*,invoice_payer_allocations'
    )
    puts trans.json()
end
<?php
$invoice = Place\Invoice::get('1QbV4MOnHKH9GeKeb');

if ( !invoice.paid ) {
    trans = Place\Transaction::create(array(
        'account_id' => $invoice.payers[0].account_id,
        'amount' => $invoice.amount_allocated,
        'type' => 'charge',
        'invoice_payer_allocations' => array(
            Place\TransactionAllocation::new(array(
                amount=>$invoice.amount_allocated,
                invoice_payer_id=>$invoice.payers[0].id
            ))
        ),
        fields=>'*,invoice_payer_allocations'
    ));
}
?>
invoice = place.Invoice.get('1QbV4MOnHKH9GeKeb')
    .then(function( invoice ){
        if ( !invoice.paid )
            trans = place.Transaction.create({
                account_id: invoice.payers[0].account_id,
                amount: invoice.amount_allocated,
                type: 'charge',
                invoice_payer_allocations: [
                    place.TransactionAllocation({
                        amount: invoice.amount_allocated,
                        invoice_payer_id: invoice.payers[0].id
                    })
                ],
              fields: '*,invoice_payer_allocations'
            })
    })
var invoice = PlaceInvoice.get("1QbV4MOnHKH9GeKeb");

if ( !invoice.paid ) {
    var trans = place.Transaction.create(new {
        account_id=invoice.payers[0].account_id,
        amount=invoice.amount_allocated,
        type="charge",
        invoice_payer_allocations=new[]{
            place.TransactionAllocation(new{
                amount=invoice.amount_allocated,
                invoice_payer_id=invoice.payers[0].id
            })
        }
    }, new { fields="*,invoice_payer_allocations" });
}

Properties

Get units, leases, invoices

# Using curl, you can pass the API key with each request
curl -s "https://api.placepay.com/units" \
-u private_key_6fsMi3GDxXg1XXSluNx1sLEd:
import place
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

units = place.Units.select()
require "place"
Place.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd"

units = Place::Units.select()

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

# 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
import place
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

units = place.Units.select()
unit = units[0]

place.Leases.update( unit.leases, due_day=1 )
require "place"
Place.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd"

units = Place::Units.select()
unit = units[0]

Place::Leases.update( unit.leases, { :due_day => 1 })
<?php
Place\Place::$api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

$units = Place\Units::select();
$unit  = $units[0];

Place\Leases::update( $unit->leases, array( 'due_day' => 1 ));
?>

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


Adding a lease

units[0]['leases'].append({
  'due_day': 1,
  'start_date': '2015-10-1',
  'rent_amount': 1000.00,
  'tenants': [{
    'email': 'john.doe@gmail.com',
    'first_name': 'John',
    'last_name': 'Doe',
  }]
})

units = requests.put('https://api.placepay.com/units',
  auth=(api_key,''), json=units).json()

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

del units[0]['leases'][-1]

units = requests.put('https://api.placepay.com/units',
  auth=(api_key,''), json=units).json()

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.rentshare.com/accounts

Embedded Resources

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

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

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

Fields

Object example

{
  "id": "1daJ3kfIHvcAAHAylDYW1dR7X", 
  "object": "account", 
  "accepted_terms": true, 
  "company": "string", 
  "email": "knowsnothing@gmail.com", 
  "full_name": "Jon Snow", 
  "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.rentshare.com/deposit_accounts

Embedded Resources

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

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

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

Fields

Object example

{
  "id": "1RMq2JCAUqhLNnJgq29dKzwaN", 
  "object": "deposit_account", 
  "accepted_terms": false, 
  "address": {}, 
  "address_id": "4D9XHwjkxLry6yGHWTyPorOZ", 
  "company": "string", 
  "default": true, 
  "deposit_method": {}, 
  "deposit_method_id": "11lgaI3lNL8c8ZJQGakL03duX", 
  "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

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

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

Transactions

This endpoint retrieves all transactions.

Resource

https://api.rentshare.com/transactions

Embedded Resources

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

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

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

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

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

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

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

Fields

Object example

{
  "id": "1KzkcFDJXvpgQFTTrLMxaz7dH", 
  "object": "transaction", 
  "account_id": "JkdQdBMmVaqHdOtWx2hpjTLZ", 
  "amount": 308.63, 
  "deposit_account_id": "bdGKuJvbhmk6WudFpt8Iq75G", 
  "description": "string", 
  "failed_timestamp": "2018-06-26 09:37:13", 
  "fee": 1.95, 
  "initiated_timestamp": "2018-06-26 09:37:13", 
  "invoice_payer_allocations": [], 
  "payment_method": {}, 
  "payment_method_id": "215yAB207B3byKSgeAfbPTApF", 
  "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
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
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.rentshare.com/transaction_allocations

Fields

Object example

{
  "id": "1jBvWfEHk8VkZjDQmT0u3dpVG", 
  "object": "transaction_allocation", 
  "amount": 485.08, 
  "invoice_description": "string", 
  "invoice_id": "21SVp4NZppbEyRr1SpbhVhkYH", 
  "invoice_payer_id": "1RUKk325aWFldDYdCPHuhekkN", 
  "status": "string", 
  "timestamp": "2018-06-26 09:37:13", 
  "transaction_id": "1ZqVWcNjBb3uexHZkyFbmWA4m"
}
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.rentshare.com/credit_ledgers

Embedded Resources

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

Fields

Object example

{
  "id": "6vxyVkf09rpqtsqMywQOfQn8", 
  "object": "transaction_ledger", 
  "account_id": "i4wUbvL5pWwdYoDKHOcfFZGI", 
  "amount": 829.6, 
  "destination_id": "J9KQIUTbBNIZ6a2ZPxnHxaOb", 
  "source_id": "1fwEnw4F0IP1mdrgNzJ39G1DW", 
  "status": "complete", 
  "timestamp": "2018-06-26 09:37:13", 
  "total_amount": 511.16, 
  "type": "charge"
}
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_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

Payment Methods

This endpoint retrieves all payment_methods.

Resource

https://api.rentshare.com/payment_methods

Embedded Resources

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

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

Fields

Object example

{
  "id": "DGarUqyHyKAFRTEu05Ow9oxn", 
  "object": "payment_method", 
  "account_id": "21JB8Y79E6FS4RFte3nCUESYR", 
  "ach_processing_approval": true, 
  "allowed_transaction_types": "charge", 
  "authorized": 568, 
  "billing_address": {}, 
  "billing_address_id": "h5y30mSmcGurCRl7fZppGe6B", 
  "birth_date": "2018-06-26", 
  "card_processing_approval": true, 
  "company": "string", 
  "company_type": "string", 
  "date_created": "2018-06-26 09:37:13", 
  "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": "CVgkOIszpxv3Q3y59JPWQyeK", 
  "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-06-26"
  }
}
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_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.rentshare.com/autopay_enrollments

Fields

Object example

{
  "id": "1UQwdKEmGQIYICjhVnXBREVtB", 
  "object": "autopay_enrollment", 
  "account_id": "1N8qVsrsjSS9FcFALQRKinjZA", 
  "deposit_account_id": "KdXi4ihppkUkZYgq7EP80LNm", 
  "enrolled_timestamp": "2018-06-26 09:37:13", 
  "last_payment_status": "string", 
  "last_payment_timestamp": "2018-06-26 09:37:13", 
  "lower_limit": 777.66, 
  "payment_method_id": "ar2vYwiyLRfclpSGC2kUVq4u", 
  "recurring_invoice_id": "bYl9sEyg6dbBUyMAWki1mPp0", 
  "upper_limit": 136.3
}
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.rentshare.com/events

Fields

Object example

{
  "id": "1Tnhq6t6EH9oamv6HtzZPE0Ny", 
  "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.rentshare.com/recurring_invoices

Embedded Resources

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

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

Fields

Object example

{
  "id": "aLSHmUPu2QwRxcij2pBD7bK5", 
  "object": "recurring_invoice", 
  "autogenerate_invoices": true, 
  "cycle_offset": 1, 
  "deposit_account_id": "2UBCOQjoh2BhLCztjZnlBSXD", 
  "end_date": "2018-06-26", 
  "invoice_template": {}, 
  "invoice_template_id": "1SUF4gL2wLQjhFjSUiDeU0Hvw", 
  "invoices": [], 
  "prorated": false, 
  "recurring_frequency": "monthly", 
  "start_date": "2018-06-26"
}
Parameter Description
id
id
readonly
Unique object identifier
object
string
readonly
Valid values: recurring_invoice
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.rentshare.com/invoices

Embedded Resources

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

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

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

Fields

Object example

{
  "id": "J2h2BhCspcT31s9HTwRqrQ3T", 
  "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-06-26 09:37:13", 
  "paid": true, 
  "payers": [], 
  "payment_records": [], 
  "payments_blocked": false, 
  "recurring_invoice_id": "Rvr2sVQXkZFEtQedw8looZbB", 
  "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.rentshare.com/invoice_payers

Embedded Resources

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

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

Fields

Object example

{
  "id": "70zmMEgv1zKjnXLeuos5EjRD", 
  "object": "invoice_payer", 
  "access": true, 
  "account_id": "3JHD9k6r8IgbtN5rvtPEB1OO", 
  "active": true, 
  "amount_allocated": 1000, 
  "amount_paid": 1000, 
  "email": "knowsnothing@gmail.com", 
  "first_name": "Jon", 
  "invoice_id": "1nIXrOKni1rXoiIKvgWuMkRwl", 
  "last_name": "Snow", 
  "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.rentshare.com/invoice_items

Embedded Resources

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

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

Fields

Object example

{
  "id": "11eNRmd4jcgWX8UdfkW0vChfT", 
  "object": "invoice_item", 
  "allocations": [], 
  "amount": 100, 
  "amount_allocated": 100, 
  "classifier": "charge", 
  "date_incurred": "2018-06-26 09:37:13", 
  "description": "Wolf Chow", 
  "invoice_id": "14rPeYytrBIrTHLWI7t7hqDXh", 
  "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.rentshare.com/invoice_item_allocations

Fields

Object example

{
  "id": "vKdmh6SuUTcSoacxHYfKiPuY", 
  "object": "invoice_item_allocation", 
  "amount": 100, 
  "item_id": "1UmIjhQVp0Gho8zcdrGtuiAHz", 
  "payer_id": "am4W1pmRrXql1OcouEfkieaM", 
  "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.rentshare.com/addresses

Fields

Object example

{
  "id": "1uESUtcIiwMbcnb40mMmZAJKe", 
  "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.rentshare.com/units

Embedded Resources

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

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

Fields

Object example

{
  "id": "OWFhyfzYcfMU88e7ridTSUI", 
  "object": "unit", 
  "active": true, 
  "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.rentshare.com/leases

Embedded Resources

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

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

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

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

Fields

Object example

{
  "id": 123, 
  "object": "lease", 
  "active": true, 
  "amount": 1500, 
  "autogenerate_invoices": true, 
  "conditional_rules": [], 
  "due_day": 1, 
  "end_date": "2016-01-01", 
  "invoices": [], 
  "lease_document": "string", 
  "payments_blocked": false, 
  "prorated": true, 
  "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.rentshare.com/tenants

Fields

Object example

{
  "id": "HvB9sGYuVt9BOOwekwv8eiMg", 
  "object": "tenant", 
  "account_id": 123, 
  "active": false, 
  "email": "knowsnothing@gmail.com", 
  "first_name": "Jon", 
  "last_name": "Snow", 
  "lease_id": 123, 
  "mobile_enabled": false, 
  "name": "string", 
  "phone": "string", 
  "recurring_payer_id": 214, 
  "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