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