NAV Navbar
cURL Node

Introduction

The Partial.ly API allows you to programmatically access the data in your Partial.ly merchant account and create payment plans and payments. The API is currently in beta mode, so there may be minor changes. If you have feedback we would love to hear it.

Our API follows REST principles and accepts and returns all data in JSON format. All requests must include the Accept: application/json HTTP header. POST and PUT data must be JSON encoded, and must have the Content-Type: application/json HTTP header. The base URL for all API calls is https://partial.ly/api.

We also have a staging server at demo.partial.ly, so if you want to test your integration please use the base URL https://demo.partial.ly/api. Note that you will have to register for a separate account here than your live Partial.ly account.

If you have any questions you can't find the answer to here, please contact our support.

Authentication

To authorize, use this code:

curl "https://partial.ly/api/offer" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

Make sure to replace your_api_key with your API key.

Partial.ly uses API keys to allow access to the API. You can find your API key in the Partial.ly merchant portal by navigating to Settings > general. If you have don't have any API key yet, click the generate key link to generate a new API key. Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth.

Partial.ly expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer your_api_key

All API requests must be made over HTTPS. Calls made over plain HTTP will be redirected to the corresponding HTTPS URL. API requests without authentication will also fail.

Pagination

Most API calls to list resources can be paginated using the following parameters. Some resources will have additional parameters you can use to filter the results.

Parameter Description
page the page number to return results for
per_page the number of results to return per page

All response objects will have the following properties, in addition to a property containing the array of results.

Name Description
page_number the current page
page_size the number of results per page
total_entires the total number of objects returned
total_pages the total number of pages found

Errors

{
    "message": "Could not create offer",
    "errors": [
        "Name: can't be blank"
    ]
}

Successful API calls will return HTTP status code 200. API calls that result in an error will either return HTTP status code 400 is there is a problem with the input, or 404 if a given object could not be found. The response body will be JSON object with a message key giving an overview of the issue. If there are issues with specific fields, there will also be an errors key with an array of field specific errors.

Offers

An offer is a set of terms for a potential payment plan. Think of an offer as a template for a payment plan. There are 3 variables that can be customized for an offer: down payment, payment frequency, and term. Offers can additionally have dynamically added line items, such as a payment plan fee or service charge, which can be a fixed amount or percent of the payment plan subtotal. Offers can be embedded on your website (Shopify, WooCommerce, etc.) to provide a payment plan checkout option for your customers. Or they can be used as template to quickly and easily create payment plans for invoices (FreshBooks, QuickBooks, Harvest)

List All Offers

curl "https://partial.ly/api/offer" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, offers) {
  // asynchronous callback function
  // offers will be already decoded JSON array of offers
});

The above command returns JSON structured like this:

[
  {
        "updated_at": "2018-10-05T14:30:20.303624",
        "term_units": "months",
        "term_min": 3,
        "term_max": 6,
        "term_flexible": true,
        "term_date": "2017-09-27",
        "term": 3,
        "require_ship_to": null,
        "payment_schedule_description": null,
        "name": "euro test",
        "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
        "integration_options": null,
        "inserted_at": "2015-09-11T05:50:30.000000",
        "id": "60aed439-473f-48e0-80ef-3a8627dd243a",
        "frequency_units": "months",
        "frequency_min": null,
        "frequency_max": null,
        "frequency_flexible": false,
        "frequency_days": [],
        "frequency": 1,
        "down_payment_type": "percent",
        "down_payment_min": 10,
        "down_payment_max": 70,
        "down_payment_flexible": false,
        "down_payment": 25,
        "currency": "EUR",
        "auto_process": true
    }
]

This endpoint retrieves all offers.

HTTP Request

GET /offer

Get a Specific Offer

curl "https://partial.ly/api/offer/60aed439-473f-48e0-80ef-3a8627dd243a" \
  -H "Authorization: Bearer your_api_key"
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer/60aed439-473f-48e0-80ef-3a8627dd243a',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, offer) {

});

The above command returns JSON structured like this:

{
    "updated_at": "2018-10-05T14:30:20.303624",
    "term_units": "months",
    "term_min": 3,
    "term_max": 6,
    "term_flexible": true,
    "term_date": "2017-09-27",
    "term": 3,
    "require_ship_to": null,
    "payment_schedule_description": null,
    "name": "euro test",
    "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
    "integration_options": null,
    "inserted_at": "2015-09-11T05:50:30.000000",
    "id": "60aed439-473f-48e0-80ef-3a8627dd243a",
    "frequency_units": "months",
    "frequency_min": null,
    "frequency_max": null,
    "frequency_flexible": false,
    "frequency_days": [],
    "frequency": 1,
    "down_payment_type": "percent",
    "down_payment_min": 10,
    "down_payment_max": 70,
    "down_payment_flexible": false,
    "down_payment": 25,
    "currency": "EUR",
    "auto_process": true
}

This endpoint retrieves a specific offer.

HTTP Request

GET /offer/:id

replace :id in the URL with the id of the offer to retrieve

Create a new offer

curl "https://partial.ly/api/offer" \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"name": "Sample offer"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    name: 'Sample offer'
  }
};

request(options, function (error, response, offer) {

});

The above command returns JSON structured like this:

{
    "updated_at": "2018-10-05T14:30:20.303624",
    "term_units": "months",
    "term_min": 0,
    "term_max": 0,
    "term_flexible": false,
    "term_date": null,
    "term": 3,
    "require_ship_to": null,
    "payment_schedule_description": null,
    "name": "Sample offer",
    "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
    "integration_options": null,
    "inserted_at": "2015-09-11T05:50:30.000000",
    "id": "60aed439-473f-48e0-80ef-3a8627dd243a",
    "frequency_units": "months",
    "frequency_min": null,
    "frequency_max": null,
    "frequency_flexible": false,
    "frequency_days": [],
    "frequency": 1,
    "down_payment_type": "percent",
    "down_payment_min": 0,
    "down_payment_max": 0,
    "down_payment_flexible": false,
    "down_payment": 0,
    "currency": "USD",
    "auto_process": true
}

This endpoint creates a new offer

HTTP Request

POST /offer

Parameters

Parameter Type Required Default Description
name string yes The name of the offer
auto_process boolean no true true to automatically schedule future payments, false for manual payments
payment_schedule_description string no for manual payment plans, a description of the payment schedule
currency string no currency in merchant settings The currency to use for payment plans
down_payment decimal no 0 the amount or percent of down payment required, depending on down_payment_type
down_payment_type string no percent "percent" for a percent of the payment plan subtotal or "fixed" for a fixed amount
down_payment_flexible boolean no false allow the customer to choose their down payment within a specified range
down_payment_min decimal no min down payment percent or amount
down_payment_max decimal no max down payment percent or amount
term integer no 3 the length of the payment plan
term_units string no months type of units for the payment plan term. weeks, months, years, payments (a fixed number of payments), or date (pay by a date)
term_date date no final payment date when using term_units=date
term_flexible boolean no false allow the customer to choose their term within the specified range
term_min integer no the minimum term the customer can choose
term_max integer no the maximum term the customer can choose
frequency integer no 1 the frequency of scheduled payments
frequency_units string no months type of units for the payment plan term. days, weeks, months, days_month (for specific days of the month)
frequency_days array no array of specific days of the month for payments, for example [1, 15] for payments on the 1st and 15th of the month
frequency_flexible boolean no false allow the customer to choose their payment frequency within the specified range
frequency_min integer no the minimum payment frequency the customer can choose
frequency_max integer no the maximum payment frequency the customer can choose
starts_auto boolean no false whether or not the first installment should automatically be scheduled relative to the date plan was opened
starts_date date no when starts_auto is false, use this date as the first scheduled installment date
starts_date_flexible boolean no false allow the customer to choose their first payment date
starts_date_max_days integer no the maximum payment frequency the customer can choose

Update an offer

curl "https://partial.ly/api/offer/60aed439-473f-48e0-80ef-3a8627dd243a" \
  -X PUT \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"down_payment": 5}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer/60aed439-473f-48e0-80ef-3a8627dd243a',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    down_payment: 5
  }
};

request(options, function (error, response, offer) {

});

The above command returns JSON structured like this:

{
    "updated_at": "2018-10-05T14:30:20.303624",
    "term_units": "months",
    "term_min": 0,
    "term_max": 0,
    "term_flexible": false,
    "term_date": null,
    "term": 3,
    "require_ship_to": null,
    "payment_schedule_description": null,
    "name": "Sample offer",
    "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
    "integration_options": null,
    "inserted_at": "2015-09-11T05:50:30.000000",
    "id": "60aed439-473f-48e0-80ef-3a8627dd243a",
    "frequency_units": "months",
    "frequency_min": null,
    "frequency_max": null,
    "frequency_flexible": false,
    "frequency_days": [],
    "frequency": 1,
    "down_payment_type": "percent",
    "down_payment_min": 0,
    "down_payment_max": 0,
    "down_payment_flexible": false,
    "down_payment": 5,
    "currency": "USD",
    "auto_process": true
}

Updates an existing offer

PUT /offer/:id

replace :id with the id of the offer to update

Same parameters as create offer

Offer Items

Offer items are additional line items that can automatically be added to a payment plan, a customer fee for instance. Offer items can be for fixed amounts or a percent of the payment plan subtotal.

List offer items

curl "https://partial.ly/api/offer_item?offer_id=60aed439-473f-48e0-80ef-3a8627dd243a" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer_item?offer_id=60aed439-473f-48e0-80ef-3a8627dd243a',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
  // body.offer_items
});

The above command returns JSON structured like this:

{
    "offer_items": [
        {
            "updated_at": "2018-10-05T14:49:20.558357",
            "offer_id": "60aed439-473f-48e0-80ef-3a8627dd243a",
            "name": "test api creation",
            "inserted_at": "2018-10-05T14:44:59.631679",
            "id": "61ed5fdf-fbdf-4b06-9a8a-0fb05cdf6f26",
            "amount_type": "percent",
            "amount": 2.2
        }
    ]
}

Gets all the offer items associated with an offer

HTTP Request

GET /offer_item

Parameters

Parameter Type Required Description
offer_id string yes offer id to get offer items for

Create a new offer item

curl "https://partial.ly/api/offer_item" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{"name": "processing fee", "amount": 2.5, "amount_type": "percent", "offer_id": "60aed439-473f-48e0-80ef-3a8627dd243a"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer_item',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    offer_id: '60aed439-473f-48e0-80ef-3a8627dd243a',
    name: 'processing fee',
    amount: 2.5,
    amount_type: 'percent'
  }
};

request(options, function (error, response, offer_item) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "updated_at": "2018-11-27T21:00:47.730189",
    "offer_id": "60aed439-473f-48e0-80ef-3a8627dd243a",
    "name": "processing fee",
    "inserted_at": "2018-11-27T21:00:47.730182",
    "id": "a9bec449-da6e-4dea-ad4a-a716aa90d40c",
    "amount_type": "percent",
    "amount": 2.5
}

Creates a new offer item associated with an offer

HTTP Request

POST /offer_item

Parameters

Parameter Type Required Default Description
name string yes The name of the offer item
offer_id string yes id of offer to associate item with
amount_type string yes either percent or fixed
amount decimal yes The amount to add to the plan. For percent will be this percent of the plan subtotal

Update offer item

curl "https://partial.ly/api/offer_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data '{"amount": 3.75}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    amount: 3.75
  }
};

request(options, function (error, response, offer_item) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "updated_at": "2018-11-27T21:00:47.730189",
    "offer_id": "60aed439-473f-48e0-80ef-3a8627dd243a",
    "name": "processing fee",
    "inserted_at": "2018-11-27T21:00:47.730182",
    "id": "a9bec449-da6e-4dea-ad4a-a716aa90d40c",
    "amount_type": "percent",
    "amount": 3.75
}

updates an existing offer item

PUT /offer_item/:id

replace :id with the id of the offer item to update

Same parameters as create offer item

Delete offer item

curl "https://partial.ly/api/offer_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c" \
  -H "Authorization: Bearer your_api_key" \
  -X DELETE
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/offer_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'DELETE'
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "OfferItem deleted"
}

deletes an offer item

DELETE /offer_item/:id

replace :id with the id of the offer item to delete

Customers

List All Customers

curl "https://partial.ly/api/customer" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, customers) {
  // asynchronous callback function
  // offers will be already decoded JSON array of customers
});

The above command returns JSON structured like this:

{
    "total_pages": 1,
    "total_entries": 2,
    "page_size": 10,
    "page_number": 1,
    "customers": [
        {
            "timezone": "America/New_York",
            "shipto_state": "FL",
            "shipto_postal_code": "33601",
            "shipto_name": "Sample Customer",
            "shipto_country": "US",
            "shipto_city": "Tampa",
            "shipto_address2": null,
            "shipto_address": "123 N. Tampa St.",
            "phone": "81325551212",
            "last_name": "Customer",
            "inserted_at": "2015-09-11T05:54:27.000000",
            "id": "6d30d3c8-d024-45cc-9c3f-356fc8aee23d",
            "first_name": "Sample",
            "email": "sample.customer@gmail.com"
        },
        {
            "timezone": "America/New_York",
            "shipto_state": null,
            "shipto_postal_code": null,
            "shipto_name": null,
            "shipto_country": null,
            "shipto_city": null,
            "shipto_address2": null,
            "shipto_address": null,
            "phone": "5042265544",
            "last_name": "Appleseed",
            "inserted_at": "2015-09-23T15:03:20.000000",
            "id": "9a426155-a927-4984-8738-0bd1ffc15248",
            "first_name": "John",
            "email": "jappleseed@yahoo.com"
        }
    ]
}

This endpoint retrieves all customers.

HTTP Request

GET /customer

Query Parameters

Parameter Description
q Search query. Will search for email if query contains an @, otherwise will search for partial match on first and last names

Get a Specific Customer

curl "https://partial.ly/api/customer/9a426155-a927-4984-8738-0bd1ffc15248" \
  -H "Authorization: Bearer your_api_key"
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/9a426155-a927-4984-8738-0bd1ffc15248',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, customer) {

});

The above command returns JSON structured like this:

{
    "timezone": "America/New_York",
    "shipto_state": null,
    "shipto_postal_code": null,
    "shipto_name": null,
    "shipto_country": null,
    "shipto_city": null,
    "shipto_address2": null,
    "shipto_address": null,
    "phone": "5042265544",
    "last_name": "Appleseed",
    "inserted_at": "2015-09-23T15:03:20.000000",
    "id": "9a426155-a927-4984-8738-0bd1ffc15248",
    "first_name": "John",
    "email": "jappleseed@yahoo.com"
}

This endpoint retrieves a specific customer.

HTTP Request

GET /customer/:id

replace :id in the URL with the id of the customer to retrieve

Create a new customer

curl "https://partial.ly/api/customer" \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"email": "testing@aol.com", "first_name": "John", "last_name": "Doe"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    email: 'testing@aol.com',
    first_name: 'John',
    last_name: 'Doe'
  }
};

request(options, function (error, response, customer) {

});

The above command returns JSON structured like this:

{
    "timezone": "America/New_York",
    "shipto_state": null,
    "shipto_postal_code": null,
    "shipto_name": null,
    "shipto_country": "US",
    "shipto_city": null,
    "shipto_address2": null,
    "shipto_address": null,
    "phone": null,
    "last_name": "Doe",
    "inserted_at": "2018-11-27T20:10:19.437168",
    "id": "53479e98-27a9-49e2-856c-bf47d0796ffc",
    "first_name": "John",
    "email": "testing@aol.com"
}

This endpoint creates a new customer

HTTP Request

POST /customer

Parameters

Parameter Type Required Default Description
email string yes Customer email
first_name string no First name
last_name string no Last name
phone string no Phone number
language string no en Customer interface display language
timezone string no America/New_York timezone for date formatting
shipto_name string no default ship to name for customer's payment plans
shipto_address string no street address
shipto_address2 string no street address line 2
shipto_city string no city
shipto_state string no 2 letter state/province/region code
shipto_country string no US 2 letter country code
shipto_postal_code string no ZIP/postal code
password string no if a new user is being created, use the supplied password. Otherwise a random password will be generated

Update a customer

curl "https://partial.ly/api/customer/53479e98-27a9-49e2-856c-bf47d0796ffc" \
  -X PUT \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"phone": "+12125551212"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/53479e98-27a9-49e2-856c-bf47d0796ffc',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    phone: '+12125551212'
  }
};

request(options, function (error, response, customer) {

});

The above command returns JSON structured like this:

{
    "timezone": "America/New_York",
    "shipto_state": null,
    "shipto_postal_code": null,
    "shipto_name": null,
    "shipto_country": "US",
    "shipto_city": null,
    "shipto_address2": null,
    "shipto_address": null,
    "phone": "+12125551212",
    "last_name": "Doe",
    "inserted_at": "2018-11-27T20:10:19.437168",
    "id": "53479e98-27a9-49e2-856c-bf47d0796ffc",
    "first_name": "John",
    "email": "testing@aol.com"
}

Updates an existing customer

PUT /customer/:id

replace :id with the id of the customer to update

Same parameters as create customer

GDPR remove

curl "https://partial.ly/api/customer/gdpr_remove/53479e98-27a9-49e2-856c-bf47d0796ffc" \
  -X PUT \
  -H "Authorization: Bearer your_api_key"
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/gdpr_remove/53479e98-27a9-49e2-856c-bf47d0796ffc',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true
};

request(options, function (error, response, body) {

});

The above command returns JSON structured like this:

{
    "message": "Customer account deleted"
}

Removal of customer information for GDPR. Customers with open payment plans cannot be deleted. If the customer has payment and payment plan information in Partial.ly, the payment and payment plan information will not be deleted, but all personally identifiable customer information will be anonymized. If the customer has no payment plan history all information will be deleted.

PUT /customer/gdpr_remove/:id

replace :id with the id of the customer to to remove

Log in with password

curl "https://partial.ly/api/customer/login_password" \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"email": "aaa@y.co", "password": "test"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/login_password',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    email: 'aaa@y.co',
    password: 'test'
  }
};

request(options, function (error, response, cust) {

});

The above command returns JSON structured like this:

{
    "timezone": "America/New_York",
    "shipto_state": null,
    "shipto_postal_code": null,
    "shipto_name": null,
    "shipto_country": "US",
    "shipto_city": null,
    "shipto_address2": null,
    "shipto_address": null,
    "phone": null,
    "last_name": "Person",
    "inserted_at": "2018-11-28T16:57:42.923471",
    "id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
    "first_name": "Testing",
    "email": "aaa@y.co"
}

Authenticate a customer with their email and password. Alternatively, customers can have a token generated and sent to their email with the email login token method, which can then be used to login with the login with a token method.

POST /customer/login_password

Parameters

Parameter Type Required
email string yes
password string yes

Email login token

curl "https://partial.ly/api/customer/login_email" \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"email": "aaa@y.co"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/login_email',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    email: 'aaa@y.co'
  }
};

request(options, function (error, response, body) {

});

The above command returns JSON structured like this:

{
    "message": "Token sent"
}

Generates a token which can be used with the login with a token method and emails it to the customer.

POST /customer/login_email

Parameters

Parameter Type Required
email string yes

Login with a token

curl "https://partial.ly/api/customer/login_token" \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  --data '{"token": "N5E9gL", "email": "aaa@y.co"}'
var request = require('request');

var options = {
  url: 'https://partial.ly/api/customer/login_token',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    token: 'N5E9gL',
    email: 'aaa@y.co'
  }
};

request(options, function (error, response, cust) {

});

The above command returns JSON structured like this:

{
    "timezone": "America/New_York",
    "shipto_state": null,
    "shipto_postal_code": null,
    "shipto_name": null,
    "shipto_country": "US",
    "shipto_city": null,
    "shipto_address2": null,
    "shipto_address": null,
    "phone": null,
    "last_name": "Person",
    "inserted_at": "2018-11-28T16:57:42.923471",
    "id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
    "first_name": "Testing",
    "email": "aaa@y.co"
}

Authenticate a customer with a token generated from the email a login token step.

POST /customer/login_token

Parameters

Parameter Type Required
token string yes
email string yes

Payment Methods

A saved payment method attached to a customer. May be any type of credit or debit card.

Create payment method

curl "https://partial.ly/api/payment_method" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{"type": "card", "token_id": "tok_ch", "customer_id": "452cc42f-d999-4c0f-998b-325c4e0e8f57"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_method',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    customer_id: '452cc42f-d999-4c0f-998b-325c4e0e8f57',
    type: 'card',
    token_id: 'tok_ch'
  }
};

request(options, function (error, response, payment_method) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "type": "card",
    "integration_details": {
        "last4": "0009",
        "funding": "credit",
        "exp_year": 2019,
        "exp_month": 11,
        "country": "CH",
        "brand": "Visa"
    },
    "inserted_at": "2018-11-27T21:38:39.520750",
    "id": "36afc659-f03d-485b-a850-65871fa759a7"
}

Example HTML to capture card details with Stripe.js

<form id="payment-form">
  <div id="card-element">
    <!-- A Stripe Element will be inserted here. -->
  </div>

  <button id="btnSubmit">Add Payment Method</button>
</form>

<script src="https://js.stripe.com/v3/"></script>
<script>
// partial.ly public key
var publicKey = 'pk_test_eV3vdXbE4SrfLjJYn9XUSUwx',
  stripe = Stripe(publicKey),
  elements = stripe.elements();

// Create an instance of the card Element.
var card = elements.create('card');

// Add an instance of the card Element into the `card-element` <div>.
card.mount('#card-element');

// Handle form submission.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function() {
  // tokenize payment data with Stripe
  stripe.createToken(card).then(function(result) {
    if (result.error) {
      // Inform the user if there was an error.
      alert(result.error.message);
    } else {
      // use result.token.id to send in the token_id field to Partial.ly
    }
  });
});
</script>

Payment method details must not be sent directly to Partial.ly. They need to be captured and tokenized with Stripe.js before being sent to Partial.ly.

When creating your Stripe.js object, use the following public key to initialize the Stripe SDK

pk_live_huSEiMMI7gSK7ORKzZB448xr

When testing with our Partial.ly test server, use the following public key

pk_test_eV3vdXbE4SrfLjJYn9XUSUwx

HTTP Request

GET /payment_method

Parameters

Parameter Type Required Description
customer_id string yes id of customer to associate with
type string yes "card"
token_id string no the token id returned from Stripe.js. Required for "card" type

List payment methods

curl "https://partial.ly/api/payment_method?customer_id=452cc42f-d999-4c0f-998b-325c4e0e8f57" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_method?customer_id=452cc42f-d999-4c0f-998b-325c4e0e8f57',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, payment_methods) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "payment_methods": [
        {
            "type": "card",
            "integration_details": {
                "last4": "0009",
                "funding": "credit",
                "exp_year": 2019,
                "exp_month": 11,
                "country": "CH",
                "brand": "Visa"
            },
            "inserted_at": "2018-11-27T21:38:39.520750",
            "id": "36afc659-f03d-485b-a850-65871fa759a7"
        },
        {
            "type": "bank_account",
            "integration_details": {
                "routing_number": "110000000",
                "plaid_access_token": "access-sandbox-a5232606-49c8-4768-b07e-4fd0baf38c21",
                "last4": "6789",
                "country": "US",
                "bank_name": "STRIPE TEST BANK",
                "account_holder_type": null,
                "account_holder_name": null
            },
            "inserted_at": "2018-06-05T13:33:04.980000",
            "id": "1754a33c-419f-4233-9c62-7fd9f5f7d088"
        }
    ]
}

Gets the list of payment methods associated with a customer

HTTP Request

GET /payment_method

Parameters

Parameter Type Required Description
customer_id string yes id of customer to get payment methods for

Delete payment method

curl "https://partial.ly/api/payment_method/36afc659-f03d-485b-a850-65871fa759a7" \
  -H "Authorization: Bearer your_api_key" \
  -X DELETE
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_method/36afc659-f03d-485b-a850-65871fa759a7',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'DELETE'
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "Payment method deleted"
}

Deletes a payment method. Payment methods which are attached to open payment plans may not be deleted.

DELETE /payment_method/:id

replace :id with the id of the payment method to delete

Payment Plans

Create a new payment plan

curl "https://partial.ly/api/payment_plan" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{"amount": "1000", "customer_id": "452cc42f-d999-4c0f-998b-325c4e0e8f57", "offer_id": "60aed439-473f-48e0-80ef-3a8627dd243a"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    amount: 1000,
    customer: {
      email: 'aaa@y.co',
      first_name: 'Testing',
      last_name: 'Person'
    },
    offer_id: '60aed439-473f-48e0-80ef-3a8627dd243a'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "payment_schedule": {
        "term_units": "months",
        "term": 3,
        "starts_date": null,
        "starts_auto": true,
        "repay_by_date": "2019-02-28",
        "payment_amount": 256.25,
        "num_payments": 3,
        "inserted_at": "2018-11-28T17:20:46.753612",
        "id": "8e2db276-7b45-4f1b-b479-0c25544d90c2",
        "frequency_units": "months",
        "frequency": 1,
        "down_payment_amount": 256.25,
        "description": null,
        "contract_signed_date": null,
        "contract_signature": null,
        "contract_body": "By submitting your order and authorizing the charges on your card, you are legally bound to...",
        "balance": 768.75,
        "auto_process": true,
        "amount": 1025
    },
    "payment_plan": {
        "user_agent": null,
        "subtotal": 1000,
        "status": "checkout",
        "number": null,
        "meta": null,
        "merchant_notes": null,
        "ip_address": null,
        "integration_id": null,
        "integration": null,
        "inserted_at": "2018-11-28T17:20:46.711165",
        "id": "2ab17c1a-860d-4575-be11-dcd5bbab467d",
        "customer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
        "customer": {
            "timezone": "America/New_York",
            "shipto_state": null,
            "shipto_postal_code": null,
            "shipto_name": null,
            "shipto_country": "US",
            "shipto_city": null,
            "shipto_address2": null,
            "shipto_address": null,
            "phone": null,
            "last_name": "Person",
            "inserted_at": "2018-11-28T16:57:42.923471",
            "id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
            "first_name": "Testing",
            "email": "aaa@y.co"
        },
        "currency": "USD",
        "amount_paid": 0,
        "amount": 1025
    },
    "line_items": [
        {
            "quantity": 1,
            "meta": null,
            "inserted_at": "2018-11-28T17:20:46.766599",
            "id": "f345d9da-b67f-4056-8224-f7d9599f9439",
            "dynamic_type": "generic",
            "dynamic": true,
            "description": "processing fee",
            "amount": 25
        }
    ],
    "installments": [
        {
            "scheduled": "2018-12-28T17:20:46.752714Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        },
        {
            "scheduled": "2019-01-28T17:20:46.752714Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        },
        {
            "scheduled": "2019-02-28T17:20:46.752714Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        }
    ]
}

Creates a new payment plan in checkout status. The payment schedule can automatically be created from an offer by sending an offer_id parameter, otherwise a payment_schedule can be specified. Likewise, either a customer_id for an existing customer can be specified, or a customer object can be sent and a new customer will be created, or the existing one attached. To open the payment plan, use the open method after it has been created.

A payment schedule will also be created and associated with the payment plan. The scheduled installments will also be generated and returned, but they will not be stored in the database until the payment plan is opened.

HTTP Request

POST /payment_plan

Parameters

Parameter Type Required Description
amount decimal yes total amount of the payment plan
customer_id string no id of customer to associate with, required if customer not set
customer object no customer object to associate with, required if customer_id not set
offer_id string no id of offer to use to generate payment schedule, required if payment_schedule not set
payment_schedule object no payment schedule parameters, required if offer_id not set
meta object no any custom meta data. May also set line_items key to an array of line_items (see below)
currency string no 3 letter currency code. Default to USD
ip_address string no ip address of customer
user_agent string no user agent of customer
shipto_name string no shipping address name
shipto_address string no street address
shipto_address2 string no street address line 2
shipto_city string no city
shipto_state string no 2 letter state/region/province code
shipto_postal_code string no zip/postal code
shipto_country string no 2 letter country abbreviation
integration string no third party integration to send payment plan to. shopify, woocommerce, bigcommerce, opencart, or prestashop
status string no checkout or pending. default is checkout
send_plan_request string no set to true to send a plan request email to customer to complete checkout. plan must be in pending status

line_items

Parameter Type Required Description
name string yes description of the line item
price decimal yes unit price of the line item
quantity integer yes quantity
image string no URL for an image to display in Partial.ly
weight decimal no weight of the item
weight_units string no lb, g, kg, oz
meta object no additional meta data for line item. For Shopify integrations, meta.product_id and meta.variant_id must be set

Open a payment plan

curl "https://partial.ly/api/payment_plan/open/ef2b5088-10cc-4246-914d-1f2de7a4075c" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data '{"payment_schedule": {"contract_signature": "Customer Signature"}, "payment_method": {"type": "card", "token_id": "tok_ch"}}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan/open/ef2b5088-10cc-4246-914d-1f2de7a4075c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    payment_schedule: {
      contract_signature: 'Customer Signature'
    },
    payment_method: {
      type: 'card',
      token_id: 'tok_ch'
    }
  }
};

request(options, function (error, response, payment_plan) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "user_agent": null,
    "subtotal": 6981,
    "status": "open",
    "number": 142,
    "meta": {
        "quickbooks_invoice_number": "1045",
        "description": "Payment Plan for invoice 1045"
    },
    "merchant_notes": null,
    "ip_address": null,
    "integration_id": "167",
    "integration": "quickbooks",
    "inserted_at": "2018-11-05T22:19:33.441694",
    "id": "ef2b5088-10cc-4246-914d-1f2de7a4075c",
    "customer_id": "b4b15b3b-281a-41be-9690-e7f51666b8ef",
    "currency": "USD",
    "amount_paid": 30,
    "amount": 7330.05
}

Opens a payment plan by signing the customer contract, attaching a payment method (new or existing), and processing the down payment if there is one. Only payment plans in checkout or pending status can be opened.

In case the supplied payment method requires 3d secure authentication (required for Strong Customer Authentication), the resulting payment plan will have status "requires_action" and will contain the "redirect_url" key. In this scenario, you should redirect the user to the "redirect_url" to authorize the payment, after which point they will be redirected back to the "return_url" you provide.

HTTP request

PUT /payment_plan/open/:id

replace :id with the id of the payment plan to open

Parameters

Parameter Type Required Description
payment_schedule.contract_signature string yes customer's signature
payment_method.id string no existing payment method id
payment_method.type string no "card", required if payment_method.id not sent
payment_method.token_id string no see Payment Methods for details on creating new payment methods
return_url string no your URL to redirect user to after 3d secure authentication

Cancel a payment plan

curl "https://partial.ly/api/payment_plan/cancel/ef2b5088-10cc-4246-914d-1f2de7a4075c" \
  -H "Authorization: Bearer your_api_key" \
  -X PUT
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan/cancel/ef2b5088-10cc-4246-914d-1f2de7a4075c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT'
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "PaymentPlan canceled"
}

Cancels a payment plan. Only payment plans in open or pending status may be canceled

HTTP Request

PUT /payment_plan/cancel/:id replace :id with the id of the payment plan to cancel

Parameter Type Required Description
cancel_shopify boolean no if this payment plan is for a Shopify order, also cancel the Shopify order
cancel_shopify_restock boolean no if this payment plan is for a Shopify order, also restock the items from the order

Update a payment plan

curl "https://partial.ly/api/payment_plan/cancel/8f999efe-5798-4b51-a6c5-d21b0d04124b" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  -- data '{"merchant_notes": "Customer is very happy"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan/8f999efe-5798-4b51-a6c5-d21b0d04124b',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    merchant_notes: 'Customer is very happy'
  }
};

request(options, function (error, response, plan) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "user_agent": null,
    "subtotal": 1000,
    "status": "open",
    "number": 140,
    "meta": {
        "items": [
            {
                "quantity": 1,
                "price": 900,
                "name": "Widget",
                "id": "widget-id"
            },
            {
                "quantity": 2,
                "price": 50,
                "name": "Small product",
                "id": "prod-sm"
            }
        ],
        "description": "Sample api plan"
    },
    "merchant_notes": "Customer is very happy",
    "ip_address": null,
    "integration_id": null,
    "integration": null,
    "inserted_at": "2018-11-28T17:13:14.181300",
    "id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
    "customer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
    "currency": "USD",
    "amount_paid": 256.25,
    "amount": 1025
}

Updates an existing payment plan

HTTP Request

PUT /payment_plan/:id replace :id with the id of the plan to update

Parameters

only the following properties may be updated

Parameter Type Description
merchant_notes string general notes, not visible to customer
payment_method_id string id of a payment method to use when processing payments for this plan
shipto_name string
shipto_address string
shipto_address2 string
shipto_city string
shipto_state string
shipto_postal_code string
shipto_country string
integration string third party service to integrate plan with, for example "shopify"
integration_id string third party service id, for example shopify order id

Retrieve a payment plan

curl "https://partial.ly/api/payment_plan/cancel/8f999efe-5798-4b51-a6c5-d21b0d04124b" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan/8f999efe-5798-4b51-a6c5-d21b0d04124b',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'GET'
};

request(options, function (error, response, plan) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "refunds": [
        {
            "status": "succeeded",
            "reason": "requested_by_customer",
            "processor_id": "re_1DbaweEs15StTpSviCrp112t",
            "processor": "stripe",
            "notes": "discount",
            "inserted_at": "2018-11-28T21:51:46.423002",
            "id": "a0990737-9234-44fc-857b-eac7b4ef3cbf",
            "failure_reason": null,
            "failure_merchant_transfer_id": null,
            "amount": 5.99
        }
    ],
    "payments": [
        {
            "status": "paid",
            "retry_number": 0,
            "processor_id": "ch_1DbXklEs15StTpSvJfo02FRM",
            "processor_destination_id": "py_E3f42E5m2H1p8b",
            "processor": "stripe",
            "payment_plan_id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
            "paid_at": "2018-11-28T18:27:16",
            "message": null,
            "inserted_at": "2018-11-28T18:27:16.896811",
            "id": "2d1d0234-87c4-4184-a49f-02f4c0c30abe",
            "currency": "USD",
            "amount": 256.25
        },
        {
            "status": "paid",
            "retry_number": 0,
            "processor_id": "ch_1DbaigEs15StTpSvhzmfGjSA",
            "processor_destination_id": "py_E3i82Rh38K8Wg7",
            "processor": "stripe",
            "payment_plan_id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
            "paid_at": "2018-11-28T21:37:21",
            "message": null,
            "inserted_at": "2018-11-28T21:37:21.296658",
            "id": "291221ab-b0a2-41dc-909b-1d1793bd23d8",
            "currency": "USD",
            "amount": 256.25
        }
    ],
    "payment_schedule": {
        "term_units": "months",
        "term": 3,
        "starts_date": null,
        "starts_auto": true,
        "repay_by_date": "2019-02-28",
        "payment_amount": 256.25,
        "num_payments": 3,
        "inserted_at": "2018-11-28T17:13:14.235119",
        "id": "1f5d9716-a041-47ef-8c57-86af22efa31c",
        "frequency_units": "months",
        "frequency": 1,
        "down_payment_amount": 256.25,
        "description": null,
        "contract_signed_date": "2018-11-28T18:27:17",
        "contract_signature": "Customer Signature",
        "contract_body": "By submitting your order and authorizing...",
        "balance": 768.75,
        "auto_process": true,
        "amount": 1025
    },
    "payment_plan": {
        "user_agent": null,
        "subtotal": 1000,
        "status": "open",
        "number": 140,
        "offer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
        "meta": {
            "items": [
                {
                    "quantity": 1,
                    "price": 900,
                    "name": "Widget",
                    "id": "widget-id"
                },
                {
                    "quantity": 2,
                    "price": 50,
                    "name": "Small product",
                    "id": "prod-sm"
                }
            ],
            "description": "Sample api plan"
        },
        "merchant_notes": "Customer is very happy",
        "ip_address": null,
        "integration_id": null,
        "integration": null,
        "inserted_at": "2018-11-28T17:13:14.181300",
        "id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
        "customer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
        "customer": {
            "timezone": "America/New_York",
            "shipto_state": "FL",
            "shipto_postal_code": "33601",
            "shipto_name": "Sample Customer",
            "shipto_country": "US",
            "shipto_city": "Tampa",
            "shipto_address2": null,
            "shipto_address": "123 N. Tampa St.",
            "phone": "81325551212",
            "last_name": "Customer",
            "inserted_at": "2015-09-11T05:54:27.000000",
            "id": "6d30d3c8-d024-45cc-9c3f-356fc8aee23d",
            "first_name": "Sample",
            "email": "sample.customer@gmail.com"
        },
        "currency": "USD",
        "balance": 518.49,
        "amount_refunded": 5.99,
        "amount_pending": 0,
        "amount_paid": 512.5,
        "amount_disputed": 0,
        "amount": 1025
    },
    "line_items": [
        {
            "quantity": 1,
            "meta": {
                "quantity": 1,
                "price": 900,
                "name": "Widget",
                "id": "widget-id"
            },
            "inserted_at": "2018-11-28T17:13:14.262856",
            "id": "0da61119-ca96-410b-a1cb-ca059f2f8395",
            "dynamic_type": "generic",
            "dynamic": false,
            "description": "Widget",
            "amount": 900
        },
        {
            "quantity": 2,
            "meta": {
                "quantity": 2,
                "price": 50,
                "name": "Small product",
                "id": "prod-sm"
            },
            "inserted_at": "2018-11-28T17:13:14.264749",
            "id": "16aa3a67-5efb-42c4-8b3b-e59940a7423f",
            "dynamic_type": "generic",
            "dynamic": false,
            "description": "Small product",
            "amount": 50
        },
        {
            "quantity": 1,
            "meta": null,
            "inserted_at": "2018-11-28T17:13:14.249186",
            "id": "1b7c8912-ee07-4731-a301-503160dc3365",
            "dynamic_type": "generic",
            "dynamic": true,
            "description": "processing fee",
            "amount": 25
        }
    ],
    "installments": [
        {
            "scheduled": "2018-12-28T18:27:16.910618",
            "retry_number": 0,
            "inserted_at": "2018-11-28T18:27:16.911366",
            "id": "6a85b229-69e6-4850-8309-edf7bfc3cec1",
            "amount": 256.25
        },
        {
            "scheduled": "2019-01-28T18:27:16.910618",
            "retry_number": 0,
            "inserted_at": "2018-11-28T18:27:16.927898",
            "id": "0caa4d95-2252-4855-8f78-a0ecf426bf09",
            "amount": 256.25
        },
        {
            "scheduled": "2019-02-28T18:27:16.910618",
            "retry_number": 0,
            "inserted_at": "2018-11-28T18:27:16.931100",
            "id": "7a6c0aba-1b55-43dc-8367-d7fada4f1bfa",
            "amount": 256.25
        }
    ],
    "disputes": []
}

Retrieves an existing payment plan

HTTP Request

GET /payment_plan/:id replace :id with the id of the plan

List all plans

curl "https://partial.ly/api/payment_plan?date=2018-11-28" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan?date=2018-11-28',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "total_pages": 1,
    "total_entries": 1,
    "payment_plans": [
        {
            "user_agent": null,
            "subtotal": 1000,
            "status": "open",
            "number": 140,
            "offer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
            "meta": {
                "items": [
                    {
                        "quantity": 1,
                        "price": 900,
                        "name": "Widget",
                        "id": "widget-id"
                    },
                    {
                        "quantity": 2,
                        "price": 50,
                        "name": "Small product",
                        "id": "prod-sm"
                    }
                ],
                "description": "Sample api plan"
            },
            "merchant_notes": "Customer is very happy",
            "ip_address": null,
            "integration_id": null,
            "integration": null,
            "inserted_at": "2018-11-28T17:13:14.181300",
            "id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
            "customer_id": "e3cbf1dc-0c11-483f-b604-d44fd93aac90",
            "customer": {
                "timezone": "America/New_York",
                "shipto_state": "FL",
                "shipto_postal_code": "33601",
                "shipto_name": "Sample Customer",
                "shipto_country": "US",
                "shipto_city": "Tampa",
                "shipto_address2": null,
                "shipto_address": "123 N. Tampa St.",
                "phone": "81325551212",
                "last_name": "Customer",
                "inserted_at": "2015-09-11T05:54:27.000000",
                "id": "6d30d3c8-d024-45cc-9c3f-356fc8aee23d",
                "first_name": "Sample",
                "email": "sample.customer@gmail.com"
            },
            "currency": "USD",
            "amount_paid": 256.25,
            "amount": 1025,
            "line_items": [
              {
                  "quantity": 1,
                  "meta": {
                      "quantity": 1,
                      "price": 900,
                      "name": "Widget",
                      "id": "widget-id"
                  },
                  "inserted_at": "2018-11-28T17:13:14.262856",
                  "id": "0da61119-ca96-410b-a1cb-ca059f2f8395",
                  "dynamic_type": "generic",
                  "dynamic": false,
                  "description": "Widget",
                  "amount": 900
              }
            ],
            "payment_schedule": {
                "term_units": "months",
                "term": 3,
                "starts_date": null,
                "starts_auto": true,
                "repay_by_date": "2019-02-28",
                "payment_amount": 256.25,
                "num_payments": 3,
                "inserted_at": "2018-11-28T17:13:14.235119",
                "id": "1f5d9716-a041-47ef-8c57-86af22efa31c",
                "frequency_units": "months",
                "frequency": 1,
                "down_payment_amount": 256.25,
                "description": null,
                "contract_signed_date": "2018-11-28T18:27:17",
                "contract_signature": "Customer Signature",
                "contract_body": "By submitting your order and authorizing...",
                "balance": 768.75,
                "auto_process": true,
                "amount": 1025,
                "installments": [
                    {
                        "scheduled": "2018-12-28T18:27:16.910618",
                        "retry_number": 0,
                        "inserted_at": "2018-11-28T18:27:16.911366",
                        "id": "6a85b229-69e6-4850-8309-edf7bfc3cec1",
                        "amount": 256.25
                    },
                    {
                        "scheduled": "2019-01-28T18:27:16.910618",
                        "retry_number": 0,
                        "inserted_at": "2018-11-28T18:27:16.927898",
                        "id": "0caa4d95-2252-4855-8f78-a0ecf426bf09",
                        "amount": 256.25
                    },
                    {
                        "scheduled": "2019-02-28T18:27:16.910618",
                        "retry_number": 0,
                        "inserted_at": "2018-11-28T18:27:16.931100",
                        "id": "7a6c0aba-1b55-43dc-8367-d7fada4f1bfa",
                        "amount": 256.25
                    }
                ]
            }
        }
    ],
    "page_size": 10,
    "page_number": 1
}

Lists all payment plans, with the optional filters listed below

HTTP Request

GET /payment_plan

Parameters

Parameter Type Description
status string plan status. checkout, pending, open, paid, canceled, or defaulted
currency string 3 letter currency code
date date plan created date. YYYY-MM-DD
dateRange string plans created in a range of dates separated by the | character. Ex. use "2018-01-01|2018-02-01"
customer string plans with the given customer id

Send plan request email

curl "https://partial.ly/api/payment_plan/send_plan_request/8f999efe-5798-4b51-a6c5-d21b0d04124b" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data ''
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_plan/send_plan_request/8f999efe-5798-4b51-a6c5-d21b0d04124b',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {}
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "Plan request email sent"
}

Send an emailed request to the customer to open the payment plan via Partially checkout. The payment plan must be in pending, canceled, defaulted, or paused status, and the merchant account must have an active Stripe account connected.

You can optionally choose to also update the payment plan status to pending, which will also allow the customer to open the payment plan from their portal.

HTTP Request

POST /payment_plan/send_plan_request/:id

Parameter Type Description
update_status string can only be updated to "pending"

Line Items

Create a line item

curl "https://partial.ly/api/line_item" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  -- data '{"payment_plan_id": "4a2da2b5-ccbc-4631-93ad-ea30da49a412", "amount": 5.99, "description": "adjustment"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/line_item',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_plan_id: '4a2da2b5-ccbc-4631-93ad-ea30da49a412',
    amount: 5.99,
    description: 'adjustment'
  }
};

request(options, function (error, response, payment) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "amount": 5.99,
    "description": "adjustment",
    "dynamic": false,
    "dynamic_type": "generic",
    "id": "2faa91f1-7b01-4111-9af9-967e70c272e8",
    "inserted_at": "2019-02-22T15:24:23",
    "meta": null,
    "quantity": 1
}

Adds a new line item to a payment plan. This can only be done on payment plans not in the open or paid statuses.

Adding a new line item to a payment plan will automatically adjust the payment plan total.

Line item amounts can be negative to decrease a payment plan amount, for example to give a customer a discount.

HTTP Request

POST /line_item

Parameters

Parameter Type Required Description
payment_plan_id string yes id of the plan to make a payment on
amount decimal yes The unit price of the line item. May be positive or negative
description string yes the line item's description
quantity integer no Th quantity of the line item. Defaults to 1 if not specified
image string no URL to an image for the line item
weight decimal no weight of the line item
weight_units string no g, kg, oz, or lb. defaults to lb
meta object no additional meta information about the line item
integration string no third party service to send line item to, ex. "shopify" or "bigcommerce"
integration_id string no line item id for third party service

Delete a line item

curl "https://partial.ly/api/line_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c" \
  -H "Authorization: Bearer your_api_key" \
  -X DELETE
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/line_item/a9bec449-da6e-4dea-ad4a-a716aa90d40c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'DELETE'
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "LineItem deleted"
}

Deletes a line item. This can only be done on payment plans not in the open or paid statuses.

Deleting a line item will automatically decrease the associated payment plan's total amount.

DELETE /line_item/:id

replace :id with the id of the line item to delete

Payments

Payments can have a paid, pending, or failed status. Payments made with a bank account payment method will be pending for up to 5 business days while we wait for them to be confirmed.

Create a payment

Pay the entire balance

curl "https://partial.ly/api/payment/create" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  -- data '{"payment_plan_id": "1597c18b-ffd4-4641-b2ca-78cccd3547f5", "amount": 241.87}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment/create',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_plan_id: '1597c18b-ffd4-4641-b2ca-78cccd3547f5',
    amount: 241.87
  }
};

request(options, function (error, response, payment) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "status": "paid",
    "retry_number": 0,
    "processor_id": "ch_1DbYxLEs15StTpSvFVKDzPIx",
    "processor_destination_id": null,
    "processor": "stripe",
    "payment_plan_id": "1597c18b-ffd4-4641-b2ca-78cccd3547f5",
    "paid_at": "2018-11-28T19:44:21",
    "message": null,
    "inserted_at": "2018-11-28T19:44:21.874251",
    "id": "2c84ae4a-962c-479b-bed4-4696ef25099d",
    "currency": "USD",
    "amount": 241.87,
    "fee": 12.39,
    "customer_fee_amount": 0.0
}

Making a payment for an amount less than the balance

curl "https://partial.ly/api/payment/create" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  -- data '{"payment_plan_id": "027bb022-40b4-4763-945c-baddc612cbbb", "amount": 5.99}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment/create',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_plan_id: '027bb022-40b4-4763-945c-baddc612cbbb',
    amount: 5.99
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "payment_schedule": {
        "term_units": "months",
        "term": 4,
        "starts_date": null,
        "starts_auto": true,
        "repay_by_date": "2019-02-25",
        "payment_amount": 116.91,
        "num_payments": 8,
        "inserted_at": null,
        "id": null,
        "frequency_units": "weeks",
        "frequency": 2,
        "down_payment_amount": 5.99,
        "description": null,
        "contract_signed_date": null,
        "contract_signature": null,
        "contract_body": "By submitting your order and authorizing the charges on your card, you are legally bound to the following terms:\r\n\r\nLayaway Agreement\r\n\r\nThis Layaway Agreement (\"Agreement\") is made...",
        "balance": 935.26,
        "auto_process": true,
        "amount": 941.25
    },
    "installments": [
        {
            "scheduled": "2018-11-24T00:00:00",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2018-12-06T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2018-12-20T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2019-01-03T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2019-01-17T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2019-01-31T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2019-02-14T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.91
        },
        {
            "scheduled": "2019-02-28T23:26:47.492554",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 116.89
        }
    ]
}

Make a payment on a payment plan for an arbitrary amount.

If the payment is for the entire remaining balance of the plan, it will be processed immediately.

If the payment is for less than the balance, a new payment schedule will need to be generated and signed by the customer. This step does not actually process the payment, but instead returns the adjusted payment schedule, installments, and contract for the customer to sign. Which is completed in the Confirm a payment step

In case the supplied payment method requires 3d secure authentication (required for Strong Customer Authentication), the resulting payment will have status "requires_action" and will contain the "redirect_url" key. In this scenario, you should redirect the user to the "redirect_url" to authorize the payment, after which point they will be redirected back to the "return_url" you provide.

HTTP Request

POST /payment/create

Parameters

Parameter Type Required Description
payment_plan_id string yes id of the plan to make a payment on
amount decimal yes amount of the payment
return_url string no your URL to redirect user to after 3d secure authentication

Confirm a payment

curl "https://partial.ly/api/payment/confirm" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  -- data '{"payment_plan_id": "027bb022-40b4-4763-945c-baddc612cbbb", "amount": 5.99, "contract_signature": "Customer signature"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment/confirm',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_plan_id: '027bb022-40b4-4763-945c-baddc612cbbb',
    amount: 5.99,
    contract_signature: 'Customer signature'
  }
};

request(options, function (error, response, payment) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "status": "paid",
    "retry_number": 0,
    "processor_id": "ch_1DbZ8sEs15StTpSvDs76XSVh",
    "processor_destination_id": null,
    "processor": "stripe",
    "payment_plan_id": "027bb022-40b4-4763-945c-baddc612cbbb",
    "paid_at": "2018-11-28T19:56:17",
    "message": null,
    "inserted_at": "2018-11-28T19:56:17.050690",
    "id": "e632f099-4c2b-4de9-b632-3966539be2d5",
    "currency": "USD",
    "amount": 5.99,
    "fee": 0.6,
    "customer_fee_amount": 0.0
}

step 2 in making a payment on a payment plan, adjusting future installments signs the updated payment schedule contract from the create step and processes the payment

In case the supplied payment method requires 3d secure authentication, the resulting payment will have status "requires_action" and will contain the "redirect_url" key. In this scenario, you should redirect the user to the "redirect_url" to authorize the payment, after which point they will be redirected back to the "return_url" you provide.

HTTP Request

POST /payment/confirm

Parameters

Parameter Type Required Description
payment_plan_id string yes id of the plan to make a payment on
amount decimal yes amount of the payment
contract_signature string yes the customer's signature for the new payment schedule contract
return_url string no your URL to redirect user to after 3d secure authentication

List all payments

curl "https://partial.ly/api/payment" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "total_pages": 24,
    "total_entries": 234,
    "payments": [
        {
            "status": "paid",
            "retry_number": 0,
            "processor_id": "ch_1DbZ8sEs15StTpSvDs76XSVh",
            "processor_destination_id": "py_E3gVHD2z4rtVl9",
            "processor": "stripe",
            "payment_plan_id": "027bb022-40b4-4763-945c-baddc612cbbb",
            "paid_at": "2018-11-28T19:56:17",
            "message": null,
            "inserted_at": "2018-11-28T19:56:17.050690",
            "id": "e632f099-4c2b-4de9-b632-3966539be2d5",
            "currency": "USD",
            "amount": 5.99,
            "fee": 0.6,
            "customer_fee_amount": 0.0
        },
        {
            "status": "paid",
            "retry_number": 0,
            "processor_id": "ch_1DbYxLEs15StTpSvFVKDzPIx",
            "processor_destination_id": "py_E3gK6PBRACnhi5",
            "processor": "stripe",
            "payment_plan_id": "1597c18b-ffd4-4641-b2ca-78cccd3547f5",
            "paid_at": "2018-11-28T19:44:21",
            "message": null,
            "inserted_at": "2018-11-28T19:44:21.874251",
            "id": "2c84ae4a-962c-479b-bed4-4696ef25099d",
            "currency": "USD",
            "amount": 241.87,
            "fee": 12.39,
            "customer_fee_amount": 0.0
        },
        // ...
    ],
    "page_size": 10,
    "page_number": 1
}

Lists all payments, with the optional filters listed below

HTTP Request

GET /payment

Parameters

Parameter Type Description
payment_plan_id string payments only for the given plan
q string a stripe payment id
status string payment status. paid, pending, or failed
currency string 3 letter currency code
date date payment created date. YYYY-MM-DD
dateRange string payments created in a range of dates separated by the | character. Ex. use "2018-01-01|2018-02-01"
customer string payments with the given customer id

Payment Schedules

A payment schedule represents the terms and schedule for a payment plan. A payment plan can have multiple payment schedules if the customer makes a one off payment that adjusts the current payment schedule. A payment plan only has one active payment schedule

Update a payment schedule

curl "https://partial.ly/api/payment_schedule/64823d54-9d47-4cd9-9db0-b293294ca341" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  -- data '{"term": 3}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_schedule/64823d54-9d47-4cd9-9db0-b293294ca341',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT',
  json: true,
  body: {
    term: 3
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "payment_schedule": {
        "term_units": "months",
        "term": 3,
        "starts_date": null,
        "starts_auto": true,
        "repay_by_date": "2019-03-21",
        "payment_amount": 256.25,
        "num_payments": 3,
        "inserted_at": "2018-12-21T22:01:18.623163",
        "id": "64823d54-9d47-4cd9-9db0-b293294ca341",
        "frequency_units": "months",
        "frequency": 1,
        "down_payment_amount": 256.25,
        "description": null,
        "contract_signed_date": null,
        "contract_signature": null,
        "contract_body": "By submitting your order and authorizing the charges on your card...",
        "balance": 768.75,
        "auto_process": true,
        "amount": 1025
    },
    "installments": [
        {
            "scheduled": "2019-01-21T22:10:14.518787Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        },
        {
            "scheduled": "2019-02-21T22:10:14.518787Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        },
        {
            "scheduled": "2019-03-21T22:10:14.518787Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 256.25
        }
    ]
}

Can only be done for active schedules of plans in checkout status. If customer flexibility enabled, updates either the term, frequency, or down payment, and reevaluates the payment schedule and installments.

HTTP request

PUT /payment_schedule/:id

Parameters

Parameter Description
down_payment_amount amount of down payment
term term or length of payment plan
frequency frequency of payments

Get contract pdf

Gets the binary pdf of the signed contract

HTTP Request

GET /payment_schedule/contract_pdf/:id

Create a new payment schedule

curl "https://partial.ly/api/payment_schedule" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  -- data '{"payment_plan_id": "71f98dc3-6d89-4e56-b14b-c0e27dac0158", "amount": 188.88, "term": 1, "term_units": "months", "frequency": 1, "frequency_units": "weeks"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/payment_schedule',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_plan_id: '71f98dc3-6d89-4e56-b14b-c0e27dac0158',
    amount: 188.88,
    term: 1,
    term_units: 'months',
    frequency: 1,
    frequency_units: 'weeks'
  }
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "payment_schedule": {
        "term_units": "months",
        "term": 1,
        "starts_date": null,
        "starts_auto": true,
        "repay_by_date": "2018-12-26",
        "payment_amount": 47.21,
        "num_payments": 4,
        "inserted_at": "2018-11-28T20:49:46.792362",
        "id": "0ec6f76b-8675-449f-9414-ccf44cc9c148",
        "frequency_units": "weeks",
        "frequency": 1,
        "down_payment_amount": 0,
        "description": null,
        "contract_signed_date": null,
        "contract_signature": null,
        "contract_body": null,
        "balance": 188.8,
        "auto_process": true,
        "amount": 188.8
    },
    "installments": [
        {
            "scheduled": "2018-12-05T20:49:46.791705Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 47.21
        },
        {
            "scheduled": "2018-12-12T20:49:46.791705Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 47.21
        },
        {
            "scheduled": "2018-12-19T20:49:46.791705Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 47.21
        },
        {
            "scheduled": "2018-12-26T20:49:46.791705Z",
            "retry_number": 0,
            "inserted_at": null,
            "id": null,
            "amount": 47.17
        }
    ]
}

Creates a new PaymentSchedule for a PaymentPlan, making it the active schedule and deactivating all others. Can't be done for open or paid status plans.

HTTP Request

POST /payment_schedule

Parameters

Parameter Type Required Default Description
payment_plan_id string yes id of the payment plan
amount decimal yes amount of the payment schedule
auto_process boolean no true true to automatically schedule future payments, false for manual payments
description string no for manual payment schedules (auto_process=false), a description of how the payments will be processed
currency string no currency in merchant settings The currency to use for payment plans
down_payment decimal no 0 the amount or percent of down payment required, depending on down_payment_type
down_payment_type string no percent percent or amount
down_payment_flexible boolean no false allow the customer to choose their down payment within a specified range
down_payment_min decimal no min down payment percent or amount
down_payment_max decimal no max down payment percent or amount
term integer no 3 the length of the payment plan
term_units string no months type of units for the payment plan term. weeks, months, years, payments (a fixed number of payments), or date (pay by a date)
term_date date no final payment date when using term_units=date
term_flexible boolean no false allow the customer to choose their term within the specified range
term_min integer no the minimum term the customer can choose
term_max integer no the maximum term the customer can choose
frequency integer no 1 the frequency of scheduled payments
frequency_units string no months type of units for the payment plan term. days, weeks, months, days_month (for specific days of the month)
frequency_days array no array of specific days of the month for payments, for example [1, 15] for payments on the 1st and 15th of the month
frequency_flexible boolean no false allow the customer to choose their payment frequency within the specified range
frequency_min integer no the minimum payment frequency the customer can choose
frequency_max integer no the maximum payment frequency the customer can choose
starts_auto boolean no true whether or not to automatically schedule the first installment relative to today's date
starts_date string no if starts_auto is false, the specified date will be the date of the first scheduled installment. YYYY-mm-dd

Installments

Installments represent a payment to be processed in the future, as scheduled by a payment plan's payment schedule.

Pay scheduled installment

curl "https://partial.ly/api/installment/pay/6a85b229-69e6-4850-8309-edf7bfc3cec1" \
  -H "Authorization: Bearer your_api_key" \
  -X PUT
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/installment/pay/6a85b229-69e6-4850-8309-edf7bfc3cec1',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'PUT'
};

request(options, function (error, response, payment) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "status": "paid",
    "retry_number": 0,
    "processor_id": "ch_1DbaigEs15StTpSvhzmfGjSA",
    "processor_destination_id": null,
    "processor": "stripe",
    "payment_plan_id": "8f999efe-5798-4b51-a6c5-d21b0d04124b",
    "paid_at": "2018-11-28T21:37:21",
    "message": null,
    "inserted_at": "2018-11-28T21:37:21.296658",
    "id": "291221ab-b0a2-41dc-909b-1d1793bd23d8",
    "currency": "USD",
    "amount": 256.25
}

Pays a scheduled installment. Must be scheduled in the future and not already paid. If successful will return the payment.

In case the supplied payment method requires 3d secure authentication, the resulting payment will have status "requires_action" and will contain the "redirect_url" key. In this scenario, you should redirect the user to the "redirect_url" to authorize the payment, after which point they will be redirected back to the "return_url" you provide.

HTTP request

PUT /installment/pay/:id

Parameters

Parameter Type Required Description
return_url string no your URL to redirect user to after 3d secure authentication

List installments

curl "https://partial.ly/api/installment?payment_schedule_id=1f5d9716-a041-47ef-8c57-86af22efa31c" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/installment?payment_schedule_id=1f5d9716-a041-47ef-8c57-86af22efa31c',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, installments) {
  // asynchronous callback function
});

Returns an array of installments as follows

[
    {
        "scheduled": "2018-12-28T18:27:16.910618",
        "retry_number": 0,
        "inserted_at": "2018-11-28T18:27:16.911366",
        "id": "6a85b229-69e6-4850-8309-edf7bfc3cec1",
        "amount": 256.25
    },
    {
        "scheduled": "2019-01-28T18:27:16.910618",
        "retry_number": 0,
        "inserted_at": "2018-11-28T18:27:16.927898",
        "id": "0caa4d95-2252-4855-8f78-a0ecf426bf09",
        "amount": 256.25
    },
    {
        "scheduled": "2019-02-28T18:27:16.910618",
        "retry_number": 0,
        "inserted_at": "2018-11-28T18:27:16.931100",
        "id": "7a6c0aba-1b55-43dc-8367-d7fada4f1bfa",
        "amount": 256.25
    }
]

Gets all installments for the given payment_schedule_id. You can also list all upcoming installments for a customer by providing a customer_id parameter.

Refunds

Refund a payment

curl "https://partial.ly/api/refund" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{"payment_id": "2d1d0234-87c4-4184-a49f-02f4c0c30abe", "amount": 5.99, "notes": "discount"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/refund',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    payment_id: '2d1d0234-87c4-4184-a49f-02f4c0c30abe',
    amount: 5.99,
    notes: 'discount'
  }
};

request(options, function (error, response, refund) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "status": "succeeded",
    "reason": "requested_by_customer",
    "processor_id": "re_1DbaweEs15StTpSviCrp112t",
    "processor": "stripe",
    "notes": "discount",
    "inserted_at": "2018-11-28T21:51:46.423002",
    "id": "a0990737-9234-44fc-857b-eac7b4ef3cbf",
    "failure_reason": null,
    "failure_merchant_transfer_id": null,
    "amount": 5.99
}

Refunds the given amount of the payment. The refund amount must not exceed the amount of the payment or the amount not already refunded.

HTTP request

POST /refund

Parameters

Parameter Type Required Description
payment_id string yes id of the payment to refund
amount decimal yes amount to refund
notes string no

List refunds

curl "https://partial.ly/api/refund" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/refund',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, refunds) {
  // asynchronous callback function
});

Returns an array of refunds as follows

{
    "total_pages": 1,
    "total_entries": 5,
    "refunds": [
        {
            "status": "succeeded",
            "reason": "requested_by_customer",
            "processor_id": "re_1DbaweEs15StTpSviCrp112t",
            "processor": "stripe",
            "notes": "discount",
            "inserted_at": "2018-11-28T21:51:46.423002",
            "id": "a0990737-9234-44fc-857b-eac7b4ef3cbf",
            "failure_reason": null,
            "failure_merchant_transfer_id": null,
            "amount": 5.99
        },
        {
            "status": "succeeded",
            "reason": "requested_by_customer",
            "processor_id": "re_1COApEEs15StTpSviNl0Utby",
            "processor": "stripe",
            "notes": null,
            "inserted_at": "2018-05-04T20:48:22.062965",
            "id": "dd9778b8-7576-40a2-912c-223fe8a1df29",
            "failure_reason": null,
            "failure_merchant_transfer_id": null,
            "amount": 5
        },
        {
            "status": "failed",
            "reason": "requested_by_customer",
            "processor_id": "re_1BTuvkEs15StTpSvSTTpommv",
            "processor": "stripe",
            "notes": null,
            "inserted_at": "2017-11-30T16:30:34.631848",
            "id": "aad5ba81-d73a-4a99-bd82-823e490b7d68",
            "failure_reason": "customer_account_closed",
            "failure_merchant_transfer_id": "tr_1BTv3SEs15StTpSvoFttIcYV",
            "amount": 2
        },
        {
            "status": "succeeded",
            "reason": "requested_by_customer",
            "processor_id": "re_1BR0AtEs15StTpSv4nRc0UZE",
            "processor": "stripe",
            "notes": "customer was furious. oh well",
            "inserted_at": "2017-11-22T15:30:09.120225",
            "id": "be123b2d-2d0d-4d58-abab-bff04382685c",
            "failure_reason": null,
            "failure_merchant_transfer_id": null,
            "amount": 50
        },
        {
            "status": "succeeded",
            "reason": null,
            "processor_id": "re_17FoZ1Es15StTpSvXcn4uLPp",
            "processor": "stripe",
            "notes": null,
            "inserted_at": "2015-12-08T16:43:43.000000",
            "id": "6e071d81-f030-41db-8511-6aa646f6dc75",
            "failure_reason": null,
            "failure_merchant_transfer_id": null,
            "amount": 472.19
        }
    ],
    "page_size": 10,
    "page_number": 1
}

Gets all refunds

HTTP request

GET /refund

Parameters

Parameter Type Description
reason string reason for the refund. requested_by_customer, duplicate, or fraudulent
date date refund created date. YYYY-MM-DD
dateRange string refunds created in a range of dates. Ex. use "2018-01-01
customer string refunds with the given customer id

Disputes

List disputes

curl "https://partial.ly/api/dispute" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/dispute',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, disputes) {
  // asynchronous callback function
});

Returns an array of disputes as follows

[
  {
    "payment_id": "3098916e-1eb1-4a02-83a2-99e32d6d606f",
    "amount": 25.65,
    "inserted_at": "2017-09-05T07:35:45.000000",
    "status": "warning_needs_response",
    "reason": "unrecognized"
  }
]

Gets all disputes

HTTP request

GET /dispute

Parameters

Parameter Type Description
status string status of the dispute
reason string reason for the dispute
date date dispute created date. YYYY-MM-DD
dateRange string disputes created in a range of dates. Ex. use "2018-01-01
customer string disputes with the given customer id

Webhooks

Create a webhook

curl "https://partial.ly/api/webhook" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -X POST \
  --data '{"url": "http://localhost:8888/hook"}'
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/webhook',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'POST',
  json: true,
  body: {
    url: 'http://localhost:8888/hook'
  }
};

request(options, function (error, response, webhook) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "version": "2.0",
    "url": "http://localhost:8888/hook",
    "updated_at": "2018-11-28T22:22:06.355439",
    "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
    "inserted_at": "2018-11-28T22:22:06.355432",
    "id": "d5e43bed-041c-4ff4-b422-a401b10aad79",
    "event": "*"
}

Creates a new webhook. Events that can be subscribed to are plan_opened, plan_paid, plan_defaulted, payment_succeeded, and payment_failed

HTTP request

POST /webhook

Parameters

Parameter Type Required Description
url string yes complete URL of the webhook, including https
event string no the event to subscribe to, or * for all events (default)

List webhooks

curl "https://partial.ly/api/webhook" \
  -H "Authorization: Bearer your_api_key"
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/webhook',
  headers: {
    Authorization: 'Bearer your_api_key'
  }
};

request(options, function (error, response, hooks) {
  // asynchronous callback function
});

Returns an array of webhooks as follows

[
    {
        "version": "2.0",
        "url": "http://prestashop.local:8080/index.php?fc=module&module=partially&controller=notify&action=webhook",
        "updated_at": "2018-03-08T15:34:35.207108",
        "merchant_id": "60689b2d-d391-417e-9f59-7b65e3e50d8d",
        "inserted_at": "2018-03-08T15:34:35.207102",
        "id": "0aeece05-8e24-419b-a2ad-466a70de9b4b",
        "event": "*"
    }
]

Gets all webhooks

HTTP request

GET /webhook

Delete a webhook

curl "https://partial.ly/api/webhook/a9bec449-da6e-4dea-ad4a-a716aa90d40c" \
  -H "Authorization: Bearer your_api_key" \
  -X DELETE
// examples use the request library
// https://github.com/request/request
var request = require('request');

var options = {
  url: 'https://partial.ly/api/webhook/a9bec449-da6e-4dea-ad4a-a716aa90d40c',
  headers: {
    Authorization: 'Bearer your_api_key'
  },
  method: 'DELETE'
};

request(options, function (error, response, body) {
  // asynchronous callback function
});

The above command returns JSON structured like this:

{
    "message": "Webhook deleted"
}

deletes a webhook

DELETE /webhook/:id

replace :id with the id of the webhook to delete