Documentation Center

Return to Admin Dashboard
Documentation Overview

> DynamicKit Complete API Reference

NAV

Introduction

Complete API Reference

Welcome to the DynamicKit Complete API reference. This is intended for advanced users.* All responses from our API should be returned in JSON format.

Looking for the getting started guide?

To view the DynamicKit Getting Started Guide which provides examples, see: DynamicKit Getting Started Guide

Environments

Staging vs. Production

In order to allow for testing, the AcceptOn API is available in the following locations:

  • Staging: https://staging-checkout.accepton.com
  • Production: https://checkout.accepton.com

The staging environment should be used for testing. Please keep in mind that the data can be deleted at any time.

Staging credentials have limitations

Your staging credentials do not work in the production environment and vice versa. Thus, in order to test, you will need to create an account in staging and then create an account in production when you’re ready to deploy.

To actually process payments, the production environment must be used. To switch to production, simply update the URL and corresponding API key, and if the moon is in the right (meaning both correct and directional) quadrant of the sky, it should “Just Work”!

Getting Started

First, you’ll need to create an account and retrieve your API credentials:

  1. If you haven’t done so already, please create an account in the staging environment https://staging.accepton.com/sign_up
  2. Link a payment processor such as Stripe or PayPal
  3. Retrieve your API key here: https://staging.accepton.com/admin/user/profile

Next, create a payment form that you’ll use to collect payment:

  1. Click “Create a Form” in the bottom left area of the navigation
  2. Copy and paste the generated code to your site

Then, make your first transaction using the form:

  1. Generate a transaction token
  2. Pass the id attribute of the response (aka the token) into the configuration of the AcceptOn form
  3. Profit!

Authentication

AcceptOn requires an API key to gain access to, well, the actual API. After logging into accepton.com, you’ll find your API key by clicking your email address in the top right, My Profile, and then use the Secret key found under the section entitled “API keys”.

AcceptOn expects for this super secret API key to be included in all API requests found in a header that looks like the following:

Authorization: Bearer <API KEY>

For the work efficient types (aka lazy), you can also append your API key as a parameter named access_token to any request if modifying headers isn’t your thing.

Sample Request

curl "https://staging-checkout.accepton.com/ping" \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
<?php
/*
 * With service discovery
 * See: https://github.com/accepton/accepton-php#getting-started
 */

use AcceptOn\Client;

$client = Client.new(API_KEY, "staging");

/* Without service discovery */

use AcceptOn\Client;

$client = Client.new(API_KEY, "staging");
$client->setHttpClient(YOUR_HTTP_CLIENT);
$client->setMessageFactory(YOUR_MESSAGE_FACTORY);
?>

Transaction Tokens

A transaction token is used to allow for details such as the amount to charge, the currency, and application fee to be created dynamically from a trusted source. This is to ensure that no one has tampered with your transaction prior to the charge being completed.

This can either be done one time using the “Create a Form” link after signing in to https://staging.accepton.com. This is useful for creating a form with a fixed price.

Alternatively, these tokens can be generated programmatically to support dynamic pricing using an API client. For instance, this allows for the price and relevant options to be delayed until the end of the checkout process.

Transaction Token Object

Attribute Description
id
string
A unique id.
type
string
Always “transaction”.
created
string
When the token was created, in ISO 8601 format.
amount
integer
The amount in cents of the transaction.
application_fee
integer
The application fee in cents to be passed on to the processor. For use only by Applications.
currency
string
The currency to charge in ISO 4217 format (default: usd).
description
string
A description of the transaction for your own identification purposes. It could be used to include a name of the item purchased, a confirmation number, or any other identifier you want to use.

Create a Transaction Token

Sample Request

curl https://staging-checkout.accepton.com/v1/tokens \
  -X POST \
  -H "Authorization: Bearer <API KEY>" \
  -d amount=1000 \
  -d description="Hipster Flannel Tshirt"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.create_token(amount: 10_00, description: "Hipster Flannel Tshirt")
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.create_token(amount=1000, currency='usd',
                               description='Hipster Flannel Tshirt')
<?php
use AcceptOn\Client;

$client = Client.new(API_KEY, "staging");

$params = array(
 "amount" => 1000,
 "description" => "Hipster Flannel Tshirt"
);
$response = $client->createToken($params);
?>

Sample Response

{
  "id":"txn_643f20df91f94ff3b6cd614b63228419",
  "type":"transaction",
  "created":"2015-01-16T20:08:17.837Z",
  "amount":1000,
  "application_fee":null,
  "currency":null,
  "description":"Hipster Flannel Tshirt"
}

Arguments

Argument Description
amount
integer
The amount in cents of the transaction.
application_fee
integer
The application fee in cents to be passed on to the processor. For use only by Applications.
currency
string
The currency to charge in ISO 4217 format (default: usd).
description
string
A description of the transaction for your own identification purposes. It could be used to include a name of the item purchased, a confirmation number, or any other identifier you want to use.
merchant_paypal_account
string, optional
The merchant’s Paypal account when you want to pay a merchant instead of yourself. Can be used with an application fee.

Returns

A transaction token object.

Retrieve a Transaction Token

Used to retrieve the details of a transaction token that has previously been created.

Sample Request

curl https://staging-checkout.accepton.com/v1/tokens/txn_643f20df91f94ff3b6cd614b63228419 \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.token('txn_b43a7e1e51410639979ab2047c156caa')
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.token('txn_b43a7e1e51410639979ab2047c156caa')

Sample Response

{
  "id":"txn_643f20df91f94ff3b6cd614b63228419",
  "type":"transaction",
  "created":"2015-01-16T20:08:17.837Z",
  "amount":1000,
  "application_fee":null,
  "currency":null,
  "description":"Hipster Flannel Tshirt"
}

Arguments

Argument Description
id
string, required
The unique id of the transaction.

Returns

A Transaction Token object.

Charges

To charge a customer, you create a charge object using the AcceptOn form. You can query charges singularly by the id or search through the history of charges on your account.

The Charge object

AttributeDescription
id
string
The unique charge identifier.
amount
integer
The amount charged in cents.
created
datetime
The time the charge was created.
currency
string
The currency to charge in ISO format (default: usd).
description
string
The description of the charge.
metadata
hash
Any metadata associated with the charge.
refunded
boolean
Whether the charge has been refunded.
remote_id
boolean
The identifier of the charge on the processor.
status
string
The status of the charge.

Retrieve a charge

Used to retrieve the details of a charge has previously been created.

Sample Response

curl https://staging-checkout.accepton.com/v1/charges/chg_123 \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton-ruby'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.charge('chg_123')
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.charge("chg_123")
<?php
use AcceptOn\Client;

$client = Client.new(API_KEY, "staging");

$response = $client->charge("chg_123");
?>

Arguments

ArgumentDescription
id
string, required
The unique id of the charge.

Returns

A Charge object.

List Previous Charges

Search for previous charges within a data range, sorted by the field you specify.

Sample Request

curl https://staging-checkout.accepton.com/v1/charges \
  -X GET \
  -H "Authorization: Bearer <API KEY>" \
  -d amount=1000 \
  -d start_date="2015-06-01" \
  -d end_date="2015-07-01" \
  -d order_by="created_at" \
  -d order="asc"
require 'accepton-ruby'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.charges(start_date: '2015-06-01', end_date: '2015-07-01', order_by: 'created_at', order: 'asc')
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.charges(start_date='2015-06-01', end_date='2015-07-01', order_by='created_at', order='asc')
<?php
$client = Client.new(API_KEY, "staging");

$params = array(
 "start_date" => "2015-06-01",
 "end_date" => "2015-07-01",
 "order_by" => "created_at",
 "order" => "asc"
);
$response = $client->charges($params);
?>

Arguments

ArgumentDescription
amount
integer
List any charges with the amount.
start_date
string
List any charges created after the date.
end_date
string
List any charges created before the date.
order_by
string
The name of the attribute to order by.
order
string
The ordering of the list (asc, desc).

Returns

An array of Charges.

Refunds

Refunds allow the reversal of a charge that has not already been fully refunded. Partial refunds are accepted up to the total amount of the original charge.

The Refund object

Attribute Description
id
string
A unique id.
amount
integer
The amount in cents of the refund.
created
datetime
The time the refund was created, in ISO 8601 format.
currency
string
The currency to charge in ISO 4217 format (default: usd).
metadata
hash
Any metadata associated with the refund.
reason
string
The reason for the refund.

Create a Refund

Sample Request

curl https://staging-checkout.accepton.com/v1/refunds \
  -X POST \
  -H "Authorization: Bearer <API KEY>" \
  -d amount=1000 \
  -d charge_id="chg_123"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.refund(amount: 10_00, charge_id: "chg_123")
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.refund(amount=1000, charge_id="chg_123")
<?php
use AcceptOn\Client;

$client = Client.new(API_KEY, "staging");

$params = array(
 "amount" => 1000,
 "charge_id" => "chg_123"
);
$response = $client->charges($params);
?>

Sample Response

{
  "id": "ref_123",
  "amount": 1000,
  "created_at": "2015-01-16T22:45:18.357Z",
  "currency": "usd",
  "metadata": null,
  "reason": "requested_by_customer"
}

Arguments

Argument Description
amount
integer, required
The amount in cents to refund.
charge_id
string, required
The id of the charge to associate with the refund.

Returns

A Refund object.

Plans

Plans are objects containing pricing information for a recurring product(s) (usually a service). An example of a plan is a monthly gym membership named Bronze for $25/month.

The Plan object

Attribute Description
id
string
The unique id of the plan.
created_at
datetime
The time the plan was created, in ISO 8601 format.
name
string
The plan that you give your customers.
amount
integer
The amount in cents to be charged for the plan.
currency
string
The currency to charge in ISO 4217 format (default: usd).
period_unit
string
The unit of frequency of charge to be made (month or year).

Create a Plan

Sample Request

curl https://staging-checkout.accepton.com/v1/plans \
  -X POST \
  -H "Authorization: Bearer <API KEY>" \
  -d name="Test Plan" \
  -d amount=1000 \
  -d currency="usd" \
  -d period_unit="month"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.create_plan(name: 'Test Plan', amount: 1000, currency: 'usd', period_unit: 'month')
from accepton import Client

client = Client(api_key=API_KEY, environment="staging")
response = client.create_plan(name="Test Plan", amount=1000, currency="usd", period_unit="month")

Sample Response

{
  "object": "plan",
  "id": "pln_123",
  "amount": 1000,
  "created_at": "2015-08-21T20:20:14.690+00:00",
  "currency": "usd",
  "name": "Test Plan",
  "period_unit": "month"
}

Arguments

Attribute Description
name
string, required
The name of the plan.
amount
string, required
The amount to be charged in cents.
currency
string
The currency to charge in ISO 4217 format (default: usd).
period_unit
string, required
The unit of frequency of charge to be made (month or year).

Returns

A Plan object.

Retrieve a Plan

Sample Request

curl https://staging-checkout.accepton.com/v1/plans/pln_123 \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.plan('pln_123')
from accepton import Client

client = Client(api_key=API_KEY, environment="staging")
response = client.plan("pln_123")

Sample Response

{
  "object": "plan",
  "id": "pln_123",
  "amount": 1000,
  "created_at": "2015-08-21T20:20:14.690+00:00",
  "currency": "usd",
  "name": "Test Plan",
  "period_unit": "month"
}

Arguments

Argument Description
id
string, required
The unique id of the plan.

Returns

A Plan object.

List Plans

Sample Request

curl https://staging-checkout.accepton.com/v1/plans \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.plans

Sample Response

[
  {
    "object": "plan",
    "id": "pln_123",
    "amount": 1000,
    "created_at": "2015-08-21T20:20:14.690+00:00",
    "currency": "usd",
    "name": "Test Plan",
    "period_unit": "month"
  }
]

Returns

An array of Plans.

Subscriptions

Subscriptions are recurring payments for a service or product from a customer for certain period of time. Subscriptions are associated to a Plan object.

The Subscription object

Attribute Description
id
string
The unique id of the subscription.
last_billed_at
datetime
The last time the subscription was charged, in ISO 8601 format.
email
string
The email address associated with the subscription.
active
boolean
The activity status of the subscription.
plan
hash
The plan associated with the subscription.

Cancel a Subscription

Sample Request

curl https://staging-checkout.accepton.com/v1/subscriptions/sub_123/cancel \
  -X POST \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.cancel_subscription('sub_123')
from accepton import Client

client = Client(api_key=API_KEY, environment="staging")
response = client.plans()

Sample Response

{
  "object": "subscription",
  "id": "sub_123",
  "active": false,
  "email": "mycustomer@email.com",
  "last_billed_at": "2015-08-21T22:43:34.096+00:00",
  "plan": {
    "object": "plan",
    "id": "pln_965d6898b660d85b",
    "amount": 1000,
    "created_at": "2015-08-21T20:20:14.690Z",
    "currency": "usd",
    "name": "Test Plan",
    "period_unit": "month"
  }
}

Arguments

Attribute Description
id
string, required
The unique id of the subscription.

Returns

A Subscription object.

Retrieve a Subscription

Sample Request

curl https://staging-checkout.accepton.com/v1/subscriptions/sub_123 \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.subscription('sub_123')
from accepton import Client

client = Client(api_key=API_KEY, environment="staging")
response = client.subscription("sub_123")

Sample Response

{
  "object": "subscription",
  "id": "sub_123",
  "active": true,
  "email": "mycustomer@email.com",
  "last_billed_at": "2015-08-21T22:43:34.096+00:00",
  "plan": {
    "object": "plan",
    "id": "pln_965d6898b660d85b",
    "amount": 1000,
    "created_at": "2015-08-21T20:20:14.690Z",
    "currency": "usd",
    "name": "Test Plan",
    "period_unit": "month"
  }
}

Arguments

Argument Description
id
string, required
The unique id of the subscription.

Returns

A Subscription object.

List Subscriptions

Sample Request

curl https://staging-checkout.accepton.com/v1/subscriptions \
  -X GET \
  -H "Authorization: Bearer <API KEY>" \
  -d page=1 \
  -d per_page=20 \
  -d active="true"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.subscriptions(page: 1, per_page: 20, active: true)
from accepton import Client

client = Client(api_key=API_KEY, environment="staging")
response = client.subscriptions(page=1, per_page=20, active=True)

Sample Response

{
  "object": "list",
  "total": 1,
  "data": [
    {
      "object": "subscription",
      "id": "sub_123",
      "active": true,
      "email": "mycustomer@email.com",
      "last_billed_at": "2015-08-21T22:43:34.096+00:00",
      "plan": {
        "object": "plan",
        "id": "pln_965d6898b660d85b",
        "amount": 1000,
        "created_at": "2015-08-21T20:20:14.690Z",
        "currency": "usd",
        "name": "Test Plan",
        "period_unit": "month"
      }
    }
  ]
}

Arguments

Argument Description
order_by
string
The name of the attribute to order by.
order
string
The ordering of the list (asc, desc).
page
integer
The page number to retrieve.
per_page
integer
The size of the page to retrieve (max: 100).
active
boolean
The activity status to filter by.
plan.token
string
The plan id to filter by.

Returns

An array of Subscriptions.

Promo Codes

Promo codes allow you to create a code that offers a discount to your customers. When they are checking out, they will be offered the option on the form to enter a promo code, which you can give to them in marketing materials.

The Promo Code object

Attribute Description
created_at
datetime
The time the promo code was created, in ISO 8601 format.
name
string
The promo code that you give your customers.
promo_type
string
The type of promotion. One of: “amount” (for amount off purchase), “fixed_price” (to set a transaction price, i.e. of $5.00), or “percentage” (for percent off purchase).
value
float or integer
The value of the promotion. For an “amount” or “fixed_price” type, the amount in cents (i.e. 1000 is $10.00). For a “percentage” type, the percent off as a decimal (i.e. 10.0 is 10%).

Create a Promo Code

Sample Request

curl https://staging-checkout.accepton.com/v1/promo_codes \
  -X POST \
  -H "Authorization: Bearer <API KEY>" \
  -d name="20OFF" \
  -d promo_type="amount" \
  -d value=2000
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.create_promo_code(name: '20OFF', promo_type: 'amount', value: 20_00)
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.create_promo_code(name="20OFF", promo_type="amount", value=2000)

Sample Response

{
  "object": "promo_code",
  "created_at": "2015-07-16T22:47:29.591+00:00",
  "name": "20OFF",
  "promo_type": "amount",
  "value": 2000
}

Arguments

Attribute Description
name
string
The promo code that you give your customers.
promo_type
string
The type of promotion. One of: “amount” (for amount off purchase), “fixed_price” (to set a transaction price, i.e. of $5.00), or “percentage” (for percent off purchase).
value
float or integer
The value of the promotion. For an “amount” or “fixed_price” type, the amount in cents (i.e. 1000 is $10.00). For a “percentage” type, the percent off as a decimal (i.e. 10.0 is 10%).

Returns

A Promo Code object.

Retrieve a Promo Code

Sample Request

curl https://staging-checkout.accepton.com/v1/promo_codes/20OFF \
  -X GET \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.promo_code('20OFF')
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.promo_code("20OFF")

Sample Response

{
  "object": "promo_code",
  "created_at": "2015-07-16T22:47:29.591+00:00",
  "name": "20OFF",
  "promo_type": "amount",
  "value": 2000
}

Arguments

Argument Description
name
string, required
The name of the promo code.

Returns

A Promo Code object.

List Promo Codes

Sample Request

curl https://staging-checkout.accepton.com/v1/promo_codes \
  -X GET \
  -H "Authorization: Bearer <API KEY>" \
  -d page=1 \
  -d per_page=20 \
  -d promo_type="amount"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
response = client.promo_codes(page: 1, per_page: 20, promo_type: 'amount')
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
response = client.promo_codes(page=1, per_page=20, promo_type='amount')

Sample Response

{
  "object": "list",
    "total": 2,
    "data": [
      {
        "object": "promo_code",
        "created_at": "2015-09-08T21:32:56.164+00:00",
        "name": "30OFF",
        "promo_type": "amount",
        "value": 3000
      },
      {
        "object": "promo_code",
        "created_at": "2015-07-16T22:47:29.591+00:00",
        "name": "20OFF",
        "promo_type": "amount",
        "value": 2000
      }
    ]
}

Arguments

Argument Description
order_by
string
The name of the attribute to order by.
order
string
The ordering of the list (asc, desc).
page
integer
The page number to retrieve.
per_page
integer
The size of the page to retrieve (max: 100).
promo_type
string
The type of promo code to filter by.

Returns

An array of Promo Codes.

Update a Promo Code

Sample Request

curl https://staging-checkout.accepton.com/v1/promo_codes/20OFF \
  -X PUT \
  -H "Authorization: Bearer <API KEY>" \
  -d name="21OFF" \
  -d promo_type="amount" \
  -d value=2100
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
promo_code = client.promo_code('20OFF')
promo_code.name = '21OFF'
promo_code.value = 21_00
promo_code = client.update_promo_code(promo_code)
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
promo_code = client.promo_code("20OFF")
promo_code.name = "21OFF"
promo_code.value = 2100
promo_code = client.update_promo_code(promo_code)

Sample Response

{
  "object": "promo_code",
  "created_at": "2015-07-16T22:47:29.591+00:00",
  "name": "21OFF",
  "promo_type": "amount",
  "value": 2100
}

Arguments

Argument Description
name
string
The new promo code that you give your customers.
promo_type
string
The new type of promotion. One of: “amount” (for amount off purchase), “fixed_price” (to set a transaction price, i.e. of $5.00), or “percentage” (for percent off purchase).
value
float or integer
The new value of the promotion. For an “amount” or “fixed_price” type, the amount in cents (i.e. 1000 is $10.00). For a “percentage” type, the percent off as a decimal (i.e. 10.0 is 10%).

Returns

The updated Promo Code object.

Delete a Promo Code

Sample Request

curl https://staging-checkout.accepton.com/v1/promo_codes/20OFF \
  -X DELETE \
  -H "Authorization: Bearer <API KEY>"
require 'accepton'

client = AcceptOn::Client.new(api_key: API_KEY, environment: :staging)
promo_code = client.promo_code('20OFF')
deleted = client.delete_promo_code(promo_code)
from accepton import Client

client = Client(api_key=API_KEY, environment='staging')
promo_code = client.promo_code("20OFF")
deleted = client.delete_promo_code(promo_code)

Example Response

{
  "object": "promo_code",
  "created_at": "2015-07-16T22:47:29.591+00:00",
  "name": "20OFF",
  "promo_type": "amount",
  "value": 2000
}

Arguments

Argument Description
name
string
The name of the promo code that you want to delete.

Returns

The deleted Promo Code object.

Errors

The AcceptOn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid.
401 Unauthorized – Your API key is wrong.
404 Not Found – The specified resource could not be found.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Support

Please contact support@accepton.com with any questions or problems.