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
require 'place'
Place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

# Test API
require 'place'
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-api');
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

// Test API url
var place = require('place-api');
place.api_key = 'test_private_key_dwjVajaCQKO4RJuV'

// Live API url
PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

// Test API url
PlaceClient.api_key = "test_private_key_dwjVajaCQKO4RJuV";

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

Installation

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

# To install using pip:
pip install place-api

# To install using Bundler:
gem 'place-api', '~> 0.5.5'

# To install using gem:
gem install place-api

# To install using Composer:
composer require place/place-api

// To install using npm:
npm install place-api

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-api')
place.api_key = 'private_key_6fsMi3GDxXg1XXSluNx1sLEd'

PlaceClient.api_key = "private_key_6fsMi3GDxXg1XXSluNx1sLEd";

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

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

Methods

Select

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

# 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-api')
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="[email protected]" \
    -d full_name="Joe Chip" \
    -d user_type="payer"

# Single mode
account = place.Account.create(
    email='[email protected]',
    full_name='Joe Chip',
    user_type='payer'
)

# Single mode
account = Place::Account.create(
    email: '[email protected]',
    full_name: 'Joe Chip',
    user_type: 'payer'
)

<?php
# Query mode
$account = Place\Account::create(array(
    'email'=>'[email protected]',
    'full_name'=>'Joe Chip',
    'user_type'=>'payer'
));
?>

// Single mode
place.Account.create({
    email: '[email protected]',
    full_name: 'Joe Chip',
    user_type: 'payer'
}).then(function(account) {});

// Single mode
PlaceAccount account = PlaceAccount.create(new {
    email="[email protected]",
    full_name="Joe Chip",
    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="[email protected]" \
    -d [0]full_name="Joe Chip" \
    -d [0]user_type="payer" \
    -d [1]email="[email protected]" \
    -d [1]full_name="Glen Runciter" \
    -d [1]user_type="payer"

# Bulk mode
accounts = place.Account.create([
    place.Account(
        email='[email protected]',
        full_name='Joe Chip',
        user_type='payer'
    ),
    place.Account(
        email='[email protected]',
        full_name='Glen Runciter',
        user_type='payer'
    )
])

# Bulk mode
accounts = Place::Account.create([
    Place::Account.new(
        email: '[email protected]',
        full_name: 'Joe Chip',
        user_type: 'payer'
    ),
    Place::Account.new(
        email: '[email protected]',
        full_name: 'Glen Runciter',
        user_type: 'payer'
    )
])

<?php
# Bulk mode
$account = Place\Account::create(array(
    new Place\Account(array(
        'email'=>'[email protected]',
        'full_name'=>'Joe Chip',
        'user_type'=>'payer'
    )),
    new Place\Account(array(
        'email'=>'[email protected]',
        'full_name'=>'Glen Runciter',
        'user_type'=>'payer'
    ))
));
?>

// Bulk mode
place.Account.create([
    place.Account({
        email: '[email protected]',
        full_name: 'Joe Chip',
        user_type: 'payer'
    }),
    place.Account({
        email: '[email protected]',
        full_name: 'Glen Runciter',
        user_type: 'payer'
    })
]).then(function(account) {});

// Bulk mode
List<PlaceAccount> accounts = PlaceAccount.create(new[]{
    new PlaceAccount(){
        email="[email protected]",
        full_name="Joe Chip",
        user_type="payer"
    },
    new PlaceAccount(){
        email="[email protected]",
        full_name="Glen Runciter",
        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="[email protected]"

# Single mode
account.update( email="[email protected]" )

# Single mode
account.update( email: '[email protected]' )

<?php
# Single mode
$account->update(array( 'email'=>'[email protected]' ));
?>

// Single mode
account.update({ email: "[email protected]" })

// Single mode
account.update(new { email="[email protected]" });

Single mode

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

{ ... } single json object

# Query mode
curl "https://api.placepay.com/accounts/[email protected]&query_mode=1" \
    -u private_key_6fsMi3GDxXg1XXSluNx1sLEd: \
    -X PUT \
    -d email="[email protected]"

# Query mode
accounts = place.Account.select(
    email='[email protected]',
    update_all={
        'email': '[email protected]'
    }
)

# Query mode
accounts = Place::Account.select(
    email: '[email protected]',
    update_all: {
        'email' => '[email protected]'
    }
)

<?php
# Query mode
$accounts = Place\Account::select(array(
    'email'=>'[email protected]',
    'update_all'=>array(
        'email'=>'[email protected]'
    )
));
?>

// Query mode
place.Account.select({
    email: '[email protected]',
    update_all: {
        'email': '[email protected]'
    }
})

// Query mode
List<PlaceAccount> accounts = PlaceAccount.select(new {
    email="[email protected]"
}, update_all: new {
    email="[email protected]"
});

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]="[email protected]" \
    -d [1][id]="kswxX5hFW57SN7icmdcaszd4" \
    -d [1][email]="[email protected]"

# Bulk mode
accounts = place.Account.update_all([
    [ account1, { 'email': '[email protected]' } ],
    [ account2, { 'email': '[email protected]' } ]
])

# Bulk mode
accounts = Place::Account.update_all([
    [ account1, { 'email': '[email protected]' } ],
    [ account2, { 'email': '[email protected]' } ]
])

<?php
# Bulk mode
$accounts = Place\Account::update_all(array(
    array( account1, array( 'email'=>'[email protected]' )),
    array( account2, array( 'email'=>'[email protected]' ))
));
?>

// Bulk mode
place.Account.update_all([
    [ account1, { 'email': '[email protected]' } ],
    [ account2, { 'email': '[email protected]' } ]
])

// Bulk mode
List<PlaceAccount> accounts = PlaceAccount.update_all(new object[]{
    new object[]{ account1, new { email="[email protected]" } },
    new object[]{ account2, new { email="[email protected]" } }
})

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/[email protected]&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": "[email protected]",
    "first_name": "Joe",
    "invoice_id": "16mgrY95eKG6oZ1hDx3kmBOkB",
    "last_name": "Chip",
    "last_payment_date": "2015-08-28",
    "paid": true,
    "payments": [{
      "id": "258V5IKHHoYxr0qyeesqkgPgY",
      "object": "transaction",
      "account_id": "LVWc2lnL0R6MmGgzVmIzzKmo",
      "amount": 100.83,
      "deposit_account_id": "W3flrWSs1kzSCYytR3XIwjb3",
      "description": "string",
      "failed_timestamp": "2017-12-10 20:41:40",
      "fee": 1.95,
      "initiated_timestamp": "2017-12-10 20:41:40",
      "payment_method": {},
      "payment_method_id": "19QsDurdSxJ0gVNzOcQSlew3D",
      "settled": true,
      "status": "complete",
      "status_details": "string",
      "type": "charge"
    }],
    "payments_transfer_date": "2015-09-04",
    "payments_transfered": true
  }],
  "fee_settings": {}
}

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

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

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

If you are creating a parent object, then any embedded objects will be created and associated to the parent.
If you are updating a parent and pass embedded objects in the update, those embedded objects with ids will be updated, any new objects without ids will be created and associated, and any missing objects will be deleted.
If you don't want any modifications to be performed on a certain embedded object when updating a parent object, exclude the embedded objects field from the update.

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(
    place.Transaction.initiated_timestamp >= datetime.date(2018,8,1)
)

# Example of combining the `greater-than`, `less-than`, and `and` operator
transactions = place.Transaction.select(
    place.Transaction.initiated_timestamp > datetime.date(2018,8,1),
    place.Transaction.initiated_timestamp < datetime.date(2018,8,15)
)

# Example of using the `or` operator
transactions = place.Transaction.select(
    (place.Transaction.status == 'declined') | (place.Transaction.status == 'canceled')
)

# Example of using the `match` operator
transactions = place.Transaction.select(
    place.Transaction.description.contains('Rent')
)

# Putting it all together
transactions = place.Transaction.select(
    place.Transaction.initiated_timestamp > datetime.date(2018,8,1),
    place.Transaction.initiated_timestamp < datetime.date(2018,8,15),
    (place.Transaction.status == 'declined') | (place.Transaction.status == 'canceled'),
    place.Transaction.description.contains('Rent'),
    place.Transaction.amount != 100
)

# 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

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

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

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

The PlacePay API uses the following error codes:

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

Aggregate functions

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(
    place.Transaction.initiated_timestamp >= datetime.date(2018,5,1),
    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 Pay plugin. This will embed a Pay button into your form that will open a payment confirmation modal to allow your customer to enter/reuse their payment method(s), confirm, and pay.

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

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

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-api')

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="[email protected]" \
    -d full_name="Joe Chip" \
    -d user_type="payer"

# Create a payer account
account = place.Account.create(
    email='[email protected]',
    full_name='Joe Chip',
    user_type='payer'
)
# At this point store the account.id for use later

# Create a payer account
account = Place::Account.create(
    email: '[email protected]',
    full_name: 'Joe Chip',
    user_type: 'payer'
)
# At this point store the account.id for use later

<?php
# Create a payer account
$account = Place\Account::create(array(
    'email' => '[email protected]',
    'full_name' => 'Joe Chip',
    'user_type' => 'payer'
));
# At this point store the $account->id for use later
?>

// Create a payer account
place.Account.create({
    email: '[email protected]',
    full_name: 'Joe Chip',
    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="[email protected]",
    full_name="Joe Chip",
    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 PlacePay 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="[email protected]" \
    -d full_name="Joe Chip" \
    -d user_type="payer" \
    -d access_tokens[0][type]='session_access'

# Create a payer account
account = place.Account.create(
    username='your_unique_id',
    email='[email protected]',
    full_name='Joe Chip',
    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: '[email protected]',
    full_name: 'Joe Chip',
    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' => '[email protected]',
    'full_name' => 'Joe Chip',
    '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: '[email protected]',
    full_name: 'Joe Chip',
    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="[email protected]",
    full_name="Joe Chip",
    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>

If you're using autopay with the data-recurring-invoice-id parameter, you can skip the following sections. Autopay enrollments will automatically process payments on the due date of each automatically generated invoice.

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.

Paid

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

Javascript Interface Attributes

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

Deposit Plugin

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

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

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

<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.AccessToken.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::AccessToken.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\AccessToken::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.AccessToken.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
PlaceAccessToken access_token = PlaceAccessToken.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(
    place.Transaction.status=='failed',
    place.Transaction.failed_timestamp>=datetime.date(2018,11,1)
)

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(
    place.Transaction.initiated_timestamp==datetime.date(2018,8,1),
    type='chargeback',
    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": "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': '[email protected]',
    'first_name': 'Joe',
    'last_name': 'Chip',
  }]
})

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

Embedded Resources

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

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

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

Fields

{
  "id": "1WwnZk3OnInAVEW9bDA2rZ8rf", 
  "object": "account", 
  "accepted_terms": false, 
  "company": "string", 
  "email": "[email protected]", 
  "full_name": "Joe Chip", 
  "phone": "(123) 456-7890", 
  "user_type": "string"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: account
`accepted_terms` `bool`	Flag for if the user has accepted the user agreement
`company` `string`	Company name of account holder
`email` `email` `required`	Email address of account holder
`full_name` `string` `required`	Name of account holder
`phone` `phone`	Phone number of account holder
`user_type` `string` `readonly: update`	Either payer or recipient

Deposit Accounts

This endpoint retrieves all deposit_accounts.

Resource

https://api.placepay.com/deposit_accounts

Embedded Resources

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

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

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

Fields

{
  "id": "fpuDkgwvSVftuG6hS7zi4q8i", 
  "object": "deposit_account", 
  "accepted_terms": true, 
  "address": {}, 
  "address_id": "B5yPEqeQYq634MErw0INpWHr", 
  "company": "string", 
  "default": true, 
  "deposit_method": {}, 
  "deposit_method_id": "25aa0XQAMYqezsOTV6ZNOiiKA", 
  "phone": "(123) 456-7890", 
  "required_payer_auth_level": 2, 
  "transaction_limit": "float", 
  "fee_settings": {
    "bank_account": {
      "distribution": 1.0, 
      "flat": 1.95, 
      "pct": 0.0
    }, 
    "credit": {
      "distribution": 0.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }, 
    "debit": {
      "distribution": 0.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }
  }
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: deposit_account
`accepted_terms` `bool`	Flag for if the signer has accepted the processing agreements
`address` `object` `required`	Single address object
`address_id` `id` `readonly`	Id for address object
`company` `string` `required`	Company name of deposit account
`default` `bool`	Denotes if this account is the user's specified default
`deposit_method` `object`	Single payment_methods object
`deposit_method_id` `id`	Id for payment_method object
`phone` `phone` `required`	Phone number associated with the deposit account
`required_payer_auth_level` `bool` `readonly: user_sessions`	Minimum authorisation level for payers to this deposit account. Defaults to 2
`transaction_limit` `float` `readonly`	None

fee_settings:

bank_account:
`distribution` `number`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

credit:
`distribution` `number`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

debit:
`distribution` `number`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

Access Token

This endpoint retrieves all access_token.

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

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

{
  "id": "24aJtyGMNkjIUJ6rhJJDZr5XM", 
  "object": "access_token", 
  "access_token": "string", 
  "account_id": "3cWtpxgezXzo2pRGObmx6eHA", 
  "expiration": "2018-01-21 16:16:23", 
  "type": "private_key"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: access_token
`access_token` `string` `readonly`	Access token to be used for api access
`account_id` `id` `readonly`	Id for account object
`expiration` `datetime`	Date and time access token will expire
`type` `string` `required`	Valid values: private_key, user, session_access, public_key

Account Permissions

This endpoint retrieves all account_permissions.

Resource

https://api.placepay.com/account_permissions

Fields

{
  "id": "ZFiU4yT9Ux92qHBAi0EYXwaX", 
  "object": "account_permission", 
  "account_id": "1FT0UgDzNdWvGogrkNVm78iC8", 
  "method": "GET", 
  "resource": "string"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: account_permission
`account_id` `id` `readonly`	Id for account object
`method` `string` `required`	Valid values: GET, POST, PUT, DELETE, *
`resource` `string` `required`	Resource path, e.g. `/transactions`

Transactions

This endpoint retrieves all transactions.

Resource

https://api.placepay.com/transactions

Embedded Resources

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

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

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

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

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

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

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

Fields

{
  "id": "1gOwTYruaRmghwAXqwtX8meUJ", 
  "object": "transaction", 
  "account_id": "h6wQ3lj1glKroDyaC9Eqci28", 
  "amount": 79.55, 
  "amount_min": 35.00, 
  "amount_max": 900.00, 
  "deposit_account_id": "F68URveHAXl1RwGnprsr8DMP", 
  "description": "string", 
  "failed_timestamp": "2018-08-22 13:38:08", 
  "fee": 1.95, 
  "initiated_timestamp": "2018-08-22 13:38:08", 
  "invoice_payer_allocations": [], 
  "payment_method": {}, 
  "payment_method_id": "RiobId4cHhczUcJhWsuzv0v8", 
  "settled": false, 
  "status": "pending", 
  "status_details": "string", 
  "type": "charge"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: transaction
`account_id` `id` `readonly: update`	Id for account object
`amount` `number` `readonly: update`	Amount of the payment
`amount_min` `number`	Minimum payment amount accepted for transaction. Default: 0.01
`amount_max` `number`	Maximum payment amount accepted for transaction. Default: 500000.00
`deposit_account_id` `id` `readonly: update`	Id for deposit account object
`description` `string`	Description of the payment
`failed_timestamp` `datetime` `readonly`	Date the payment failed (ACH Only)
`fee` `number` `readonly: user_sessions,update`	Processing fee
`initiated_timestamp` `datetime` `readonly`	Date the payment was initiated
`invoice_payer_allocations` `list`	List of transaction_allocations objects
`payment_method` `object`	Single payment_methods object
`payment_method_id` `id` `readonly: update`	Id for payment_method object
`settled` `bool` `readonly`	Denotes if the payment has settled
`status` `string`	Valid values: pending, complete, declined, canceled, failed
`status_details` `string` `readonly: user_sessions`	Additional details on the status of the payment
`type` `string` `readonly: update`	Valid values: charge, deposit, reversal, refund, chargeback, chargeback_reversal

Transaction Allocations

This endpoint retrieves all transaction_allocations.

Resource

https://api.placepay.com/transaction_allocations

Fields

{
  "id": "25si9BOqSzgvD9xPHLxcPMdLO", 
  "object": "transaction_allocation", 
  "amount": 502.57, 
  "invoice_description": "string", 
  "invoice_id": "tw6iUk1nm2j8BPxiMRR5G8Ha", 
  "invoice_payer_id": "1xIRYJHXVLiNu4kLvzY9gqIuQ", 
  "status": "string", 
  "timestamp": "2018-08-22 13:38:08", 
  "transaction_id": "1QXTxVurSNdoMUuxodmUSriNv"
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: transaction_allocation
`amount` `number` `required`	Amount allocated to the referenced invoice payer
`invoice_description` `string` `readonly`	Invoice description
`invoice_id` `id` `readonly`	Id for invoice object
`invoice_payer_id` `id` `required`	Id for invoice_payer object
`status` `string` `readonly`	The current status of the transaction
`timestamp` `datetime` `readonly`	The timestamp of the transaction
`transaction_id` `id` `required`	Id for transaction object

Transaction Ledger

This endpoint retrieves all credit_ledgers.

Resource

https://api.placepay.com/credit_ledgers

Embedded Resources

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

Fields

{
  "id": "27FRnUePmHnVEfarGI10OE9R7", 
  "object": "transaction_ledger", 
  "account_id": "kGvJbSmy6AJBQkAGBLvrnywu", 
  "amount": 828.9, 
  "destination_id": "1q4x3VZbLeOvnrSkccy8Go8Ug", 
  "source_allocation_id": "SC0ZJxENtHkx55iZtxpvl26b", 
  "source_id": "233bgJQ6DMRAIGSUe0esPm7Fm", 
  "status": "complete", 
  "timestamp": "2018-08-22 13:38:08", 
  "total_amount": 209.76, 
  "type": "charge", 
  "viewpoint": "string"
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: transaction_ledger
`account_id` `id` `readonly`	Id for account object
`amount` `number`	Amount of ledger transfer
`destination_id` `id` `readonly`	Id for destination object
`source_allocation_id` `id`	Id for source_allocation object (if applicable)
`source_id` `id` `required`	Id for source object
`status` `string` `readonly`	Status of transaction
`timestamp` `datetime` `readonly`	Timestamp of transaction
`total_amount` `number` `readonly`	Total resulting transaction amount
`type` `string` `readonly`	Type of transaction
`viewpoint` `string` `readonly`	None

Payment Methods

This endpoint retrieves all payment_methods.

Resource

https://api.placepay.com/payment_methods

Embedded Resources

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

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

Fields

{
  "id": "zfqPG3IR2EpX7RCmYf6rk0nR", 
  "object": "payment_method", 
  "account_id": "I31sdrQugh4TExONRAF69LYJ", 
  "ach_processing_approval": false, 
  "allowed_transaction_types": "charge", 
  "authorized": 486, 
  "billing_address": {}, 
  "billing_address_id": "ZZqKk8Qpu1tblVG4W1jMow9z", 
  "birth_date": "2018-08-22", 
  "card_processing_approval": true, 
  "company": "string",
  "website_url": "https://www.example.com/",
  "established": "2009-04-10 00:00:00",
  "building_type": "Residential",
  "unit_count":200, 
  "monthly_volume": 301,
  "highest_monthly": 6500,
  "company_ownership": 593.65, 
  "company_type": "string", 
  "date_created": "2018-08-22 13:38:08", 
  "deleted": false, 
  "description": "string", 
  "ein": "string", 
  "first_name": "string", 
  "last_name": "string", 
  "phone_number": "(123) 456-7890", 
  "processing_activation_status": "pending", 
  "processor_approval": {}, 
  "processor_approval_id": "Sd3cqUqCt3AjsaLIo9F9kYui", 
  "ssn": "string", 
  "type": "card", 
  "bank_account": {
    "account_class": "string", 
    "account_number": "string", 
    "account_type": "string", 
    "routing_number": "string"
  }, 
  "card": {
    "card_brand": "string", 
    "card_code": "string", 
    "card_number": "string", 
    "card_type": "credit", 
    "expiration_date": "2018-08-22"
  }
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: payment_method
`account_id` `id` `required`	Id for account object
`ach_processing_approval` `bool` `readonly: user_sessions`	Denotes if ach payments has been approved. For disbursable payments methods only
`allowed_transaction_types` `string` `readonly: update`	Valid values: charge, charge,disburse
`authorized` `int` `readonly: user_sessions`	Denotes the authorization level of this payment method
`billing_address` `object`	Single address object
`billing_address_id` `id` `readonly`	Id for address object
`birth_date` `date`	Birth date of the account holder
`card_processing_approval` `bool` `readonly: user_sessions`	Denotes if card payments has been approved. For disbursable payments methods only
`company` `string` `required`	The legal entity name associated with the account
`company_ownership` `number` `required`	The ownership percentage of the legal entity
`company_type` `string` `required`	The legal entity type, i.e., LLC
`date_created` `datetime` `readonly`	The timestamp the payment method was added to the system
`deleted` `bool` `readonly: create`	Identifies if the payment method has been deleted or deactivated.
`description` `string` `readonly`	A human-readable description of the payment method, i.e., Visa x-4242
`ein` `string` `required`	The legal entity tax id. For disbursable payments methods only
`first_name` `string` `required`	The first name of the account holder
`last_name` `string` `required`	The last name of the account holder
`phone_number` `phone` `required`	The phone number of the account holder
`processing_activation_status` `string` `readonly`	Valid values: pending, in_review, active, inactive, action_needed
`processor_approval` `object`	Single processing_account object
`processor_approval_id` `id` `readonly`	Id of underlying processing object
`ssn` `string` `required`	The principal's social security number. For disbursable payments methods only
`type` `string` `required`	Valid values: card, bank_account

bank_account:
`account_class` `string` `readonly: update`	None
`account_number` `string` `readonly: restricted_update`	None
`account_type` `string` `readonly: restricted_update`	None
`routing_number` `string` `readonly: restricted_update`	None

card:
`card_brand` `string` `readonly`	None
`card_code` `string`	None
`card_number` `string` `readonly: update`	None
`card_type` `string` `readonly: user_sessions`	Valid values: credit, debit
`expiration_date` `date` `required`	None

Autopay Enrollments

This endpoint retrieves all autopay_enrollments.

Resource

https://api.placepay.com/autopay_enrollments

Fields

{
  "id": "gQ0HHiJrZ1ZanNcGfIvAaw2r", 
  "object": "autopay_enrollment", 
  "account_id": "MfHb7CbANIWs3oDYLfyT4NC1", 
  "deposit_account_id": "E98VpXS83zzXKA8Hx7ijbzPc", 
  "enrolled_timestamp": "2018-08-22 13:38:08", 
  "last_payment_status": "string", 
  "last_payment_timestamp": "2018-08-22 13:38:08", 
  "lower_limit": 233.37, 
  "payment_method_id": "10TYcywq1HI04qNx09Cd8fgyg", 
  "recurring_invoice_id": "22GY0oo4aHY8CpVo8kBjIzvmt", 
  "upper_limit": 845.6
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: autopay_enrollment
`account_id` `id` `readonly`	Id for account object
`deposit_account_id` `id`	Id for deposit_account object
`enrolled_timestamp` `datetime` `readonly`	Timestamp user enrolled in autopay
`last_payment_status` `string` `readonly`	Status of the last payment attempt for the account
`last_payment_timestamp` `datetime` `readonly`	Timestamp of the last payment attempt for the account
`lower_limit` `currency`	Lower limit of how much the user has allowed to auto-process
`payment_method_id` `id` `required`	Id for payment_method object
`recurring_invoice_id` `id` `readonly: update`	Id for recurring_invoice object
`upper_limit` `currency` `required`	Upper limit of how much the user has allowed to auto-process

Events

This endpoint retrieves all events.

Resource

https://api.placepay.com/events

Fields

{
  "id": "1pOw6dUon3NZ8WmgQ9KGWpGkd", 
  "object": "event", 
  "callback_url": "https://example.com/ach_failure_handler", 
  "event": "ach_failure"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: event
`callback_url` `string` `required`	Url to trigger
`event` `string` `required`	Name of event

Recurring Invoices

This endpoint retrieves all recurring_invoices.

Resource

https://api.placepay.com/recurring_invoices

Embedded Resources

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

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

Fields

{
  "id": "vIxM2IRzBwScnoS1DR2azJsW", 
  "object": "recurring_invoice", 
  "autogenerate_buffer": 87, 
  "autogenerate_invoices": true, 
  "cycle_offset": 1, 
  "deposit_account_id": "VKVYqLtAgaSa5KLIUzmc82rz", 
  "end_date": "2018-08-22", 
  "invoice_template": {}, 
  "invoice_template_id": "1yAULJ2cPp2weN6k5nkwfnPgq", 
  "invoices": [], 
  "prorated": true, 
  "recurring_frequency": "monthly", 
  "start_date": "2018-08-22"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: recurring_invoice
`autogenerate_buffer` `int`	None
`autogenerate_invoices` `bool`	Denotes whether new invoices will be automatically generated
`cycle_offset` `int`	Day of the month rent is due
`deposit_account_id` `id`	None
`end_date` `date`	End date of the recurring service period
`invoice_template` `object` `required`	Single invoice object
`invoice_template_id` `id` `readonly`	None
`invoices` `list`	List of invoice objects
`prorated` `bool`	If enabled, initial and final charges will be prorated
`recurring_frequency` `string`	Valid values: monthly, weekly
`start_date` `date`	Start date of the recurring service period

Invoices

This endpoint retrieves all invoices.

Resource

https://api.placepay.com/invoices

Embedded Resources

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

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

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

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

Fields

{
  "id": "brLufAn5APd2791lj1nRPoej", 
  "object": "invoice", 
  "accepted_payment_state": "full", 
  "amount": 1000, 
  "amount_paid": 1000, 
  "amount_unallocated": 200, 
  "completed_date": "2015-09-01", 
  "deposit_account_id": 123, 
  "description": "September Rent", 
  "due_date": "2015-09-01", 
  "items": [], 
  "last_payment_date": "2018-08-22 13:38:08", 
  "paid": true, 
  "payers": [], 
  "payment_records": [], 
  "payments_blocked": false, 
  "recurring_invoice_id": "AlH27xAPBqRCdzC9JWl7HQUa", 
  "reference_id": "Acct #ABC-123", 
  "required_payer_auth_level": 2, 
  "type": "rent", 
  "fee_settings": {
    "bank_account": {
      "distribution": 1.0, 
      "flat": 1.95, 
      "pct": 0.0
    }, 
    "credit": {
      "distribution": 1.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }, 
    "debit": {
      "distribution": 1.0, 
      "flat": 0.0, 
      "pct": 0.0299
    }
  }
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: invoice
`accepted_payment_state` `string`	Denotes whether this invoice requires payment by all tenants. Can be 'partial' or 'full'
`amount` `number` `readonly`	Amount due on this invoice
`amount_paid` `number` `readonly`	The amount that has been paid by tenants
`amount_unallocated` `number` `readonly`	Amount on this invoice that has not been allocated to individual tenants
`completed_date` `datetime` `readonly`	Date on which this invoice was paid
`deposit_account_id` `id`	Id for deposit account object
`description` `string`	Description for this invoice
`due_date` `date` `required`	The due date for this invoice
`items` `list` `required`	List of invoice_items objects
`last_payment_date` `datetime` `readonly`	Date and time of the last payment made on this invoice
`paid` `bool` `readonly`	Denotes whether this invoice has been paid
`payers` `list`	List of invoice_payers objects
`payment_records` `list`	List of invoice_payment_records objects
`payments_blocked` `bool`	Denotes whether payments are allowed on this invoice
`recurring_invoice_id` `id`	Id for recurring invoice object
`reference_id` `string`	Copied from reference_id defined in lease
`required_payer_auth_level` `bool` `readonly`	Minimum authorisation level for payers on this invoice. Defaults to 2
`type` `string` `required`	Invoice type, such as rent, fee, misc, etc.

fee_settings:

bank_account:
`distribution` `number` `readonly`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

credit:
`distribution` `number` `readonly`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

debit:
`distribution` `number` `readonly`	Denotes the fee distribution between payee and payer
`flat` `number` `readonly`	Flat fee for processing a payment
`pct` `number` `readonly`	Percent fee for processing a payment

Invoice Payers

This endpoint retrieves all invoice_payers.

Resource

https://api.placepay.com/invoice_payers

Embedded Resources

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

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

Fields

{
  "id": "1jhcsVzB1jvv47nu4sNvojj9E", 
  "object": "invoice_payer", 
  "access": true, 
  "account_id": "yos62Ggb43JZsccLD8cZ0e56", 
  "active": true, 
  "amount_allocated": 1000, 
  "amount_paid": 1000, 
  "email": "[email protected]", 
  "first_name": "Joe", 
  "invoice_id": "LQ8stUFNG1p5lVWX1Lpn6oH6", 
  "last_name": "Chip", 
  "last_payment_date": "2015-08-28", 
  "paid": true, 
  "payments_transfer_date": "2015-09-04", 
  "payments_transfered": true, 
  "transaction_allocations": []
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: invoice_payer
`access` `bool` `required`	Denotes whether this payer has been authorized access this invoice
`account_id` `id` `readonly: update`	Id for account object
`active` `bool` `readonly`	Denotes whether this payer is still active
`amount_allocated` `number` `readonly`	The amount assigned to this payer for this invoice
`amount_paid` `number` `readonly`	The amount this payer has paid for this invoice
`email` `email` `required`	Email address of account holder
`first_name` `string` `required`	First name of account holder
`invoice_id` `id` `readonly: update`	Id for invoice object
`last_name` `string`	Last name of account holder
`last_payment_date` `datetime` `readonly`	The last payment made by this payer for this invoice
`paid` `bool` `readonly`	Denotes whether this payer has paid
`payments_transfer_date` `datetime` `readonly`	The date on which the payments made by this payer were transferred to the payee
`payments_transfered` `bool` `readonly`	Denotes whether the payments made by this payer have been transferred to the payee
`transaction_allocations` `list`	List of transaction_allocations objects

Invoice Items

This endpoint retrieves all invoice_items.

Resource

https://api.placepay.com/invoice_items

Embedded Resources

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

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

Fields

{
  "id": "CA98I5I66SjsEQmIINjdExJe", 
  "object": "invoice_item", 
  "allocations": [], 
  "amount": 100, 
  "amount_allocated": 100, 
  "classifier": "charge", 
  "date_incurred": "2018-08-22 13:38:08", 
  "description": "Wolf Chow", 
  "invoice_id": "21MjSZMeU9LAQ488UNy7wkg1S", 
  "prorated": false, 
  "recurring": false, 
  "type": "Shared Expense"
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: invoice_item
`allocations` `list` `readonly`	List of invoice_item_allocation objects
`amount` `number` `required`	The amount for this invoice item
`amount_allocated` `number` `readonly`	The amount of this invoice item that has been assigned to payers
`classifier` `string`	Valid values: charge, payment
`date_incurred` `datetime`	Date the invoice item was incurred
`description` `string`	The description for this invoice item
`invoice_id` `id` `readonly: update`	Id for invoice object
`prorated` `bool` `readonly`	Date the invoice item was incurred
`recurring` `int`	Denotes whether this item recurs monthly or is a one-time item
`type` `string`	The type of this invoice item, ie. Rent, Late Fee, etc.

Invoice Item Allocations

This endpoint retrieves all invoice_item_allocations.

Resource

https://api.placepay.com/invoice_item_allocations

Fields

{
  "id": "197blt1KHVfRSxSm7q6nOadvE", 
  "object": "invoice_item_allocation", 
  "amount": 100, 
  "item_id": "1LqZzG0dz1ao4hOfMegAlsaB3", 
  "payer_id": "BQZZeTNbynKYop9spC8E8VNn", 
  "type": "auto"
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: invoice_item_allocation
`amount` `number` `required`	The amount of this assignment
`item_id` `id` `readonly`	Id for invoice item object
`payer_id` `id` `readonly`	Id for invoice payer object
`type` `string` `required`	The type of this assignment. Can be 'auto', 'custom', 'auto_payer', or 'auto_payee'

Addresses

This endpoint retrieves all addresses.

Resource

https://api.placepay.com/addresses

Fields

{
  "id": "1o5jQjKWaEsaDElh1ArwiiNPb", 
  "object": "address", 
  "address": "123 Example St, #2F", 
  "city_state_zip": "New York, NY 10001", 
  "street_address": "123 Example St", 
  "street_name": "Example St", 
  "street_number": "123", 
  "unit_number": "#2F"
}

Parameter	Description
`id` `id` `readonly`	Unique object identifier
`object` `string` `readonly`	Valid values: address
`address` `string` `readonly`	Full address and unit number, if applicable
`city_state_zip` `string` `required`	The city city, state and zipcode
`street_address` `string` `required`	The street number and name, this excludes any unit number
`street_name` `string` `readonly`	The name of the street
`street_number` `string` `readonly`	The street number
`unit_number` `string`	The unit number, `null` if N/A

Units

This endpoint retrieves all units.

Resource

https://api.placepay.com/units

Embedded Resources

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

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

Fields

{
  "id": "AUtiNNdUlGOdYb5V3eQkrkWw", 
  "object": "unit", 
  "active": false, 
  "address": {}, 
  "address_id": 123, 
  "billing_account_id": 123, 
  "building_id": 123, 
  "leases": [], 
  "price": 1000, 
  "status": "payments_allowed", 
  "type": "rental"
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: unit
`active` `bool` `readonly`	None
`address` `object` `readonly`	Single address object
`address_id` `int`	Id for address object
`billing_account_id` `int` `readonly`	Id for billing account object
`building_id` `int`	Id for building object
`leases` `list`	List of lease objects
`price` `number`	Default rent amount for this unit
`status` `string`	Verification status: payments_allowed, payments_blocked
`type` `string`	Valid values: rental, condo

Leases

This endpoint retrieves all leases.

Resource

https://api.placepay.com/leases

Embedded Resources

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

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

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

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

Fields

{
  "id": 123, 
  "object": "lease", 
  "active": false, 
  "amount": 1500, 
  "autogenerate_invoices": true, 
  "conditional_rules": [], 
  "due_day": 1, 
  "end_date": "2016-01-01", 
  "invoices": [], 
  "lease_document": "string", 
  "payments_blocked": false, 
  "prorated": false, 
  "recurring_frequency": "monthly", 
  "recurring_invoice_id": 123, 
  "recurring_invoice_template_id": 123, 
  "recurring_items": [], 
  "reference_id": "Acct #ABC-123", 
  "rent_amount": 1000, 
  "start_date": "2015-06-06", 
  "tenants": [], 
  "type": "Acct #ABC-123", 
  "unit_id": 123
}

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

Tenants

This endpoint retrieves all tenants.

Resource

https://api.placepay.com/tenants

Fields

{
  "id": "1tj6F7aguw5dQh9KefpccGcpl", 
  "object": "tenant", 
  "account_id": 123, 
  "active": true, 
  "email": "[email protected]", 
  "first_name": "Joe", 
  "last_name": "Chip", 
  "lease_id": 123, 
  "mobile_enabled": true, 
  "name": "string", 
  "phone": "string", 
  "recurring_payer_id": 601, 
  "user_id": 123
}

Parameter	Description
`id` `id`	Unique object identifier
`object` `string` `readonly`	Valid values: tenant
`account_id` `int` `readonly`	Id for account object
`active` `bool` `readonly`	None
`email` `email` `readonly: update`	Email address of account holder
`first_name` `string` `readonly: update`	First name of account holder
`last_name` `string` `readonly: update`	Last name of account holder
`lease_id` `int`	Id for lease object
`mobile_enabled` `bool` `readonly`	Denotes if user has push notification capabilities
`name` `string` `readonly: update`	Full name of resident
`phone` `string`	Phone number of resident
`recurring_payer_id` `int` `readonly`	Id for recurring invoice_payer object
`user_id` `int` `readonly`	Id for user object