isaac10 API Documentation

Welcome the the isaac10 documentation.

Overview

isaac10 offers four ways for integration. Please consult us to find out the best fitting solution for you.

Hosted Pages

isaac10 will host the forms for registering new customers and edit customer accounts. Customers can log in independently from your website. You will get notified about changes via configurable webhooks.

REST API

The REST API marks the lowest integration level. It is meant for integration with backend systems.

JavaScript API

The JavaScript library wraps the REST API. Use the JavaScript API to integrate isaac10 into your website.

isaac10 UI

The issac10 UI is an embeddable Ember.js application. Using the isaac10 UI is the easiest way to integrate isaac10 into your website.

API Integration

REST API

The REST API can be used with any HTTP client. All API requests must use HTTPS and need to be send to:

https://your-subdomain.isaac10.com

Replace your-subdomain with… well… your subdomain.

All PATCH requests may also be called as PUT requests. This does not change the functionality: Although PUT is meant to be used for replacing an entity, only the submitted data will be altered. Present and non-submitted data will stay in place.

All REST API calls will respond with the JSON content described in the right panel.

JavaScript API

Load the JavaScript library into the page and initialize the isaac10 JavaScript object as shown on the right side.

<script type="text/javascript" src="https://app.isaac10.com/api/v1/isaac10_api.js"></script>

var isaac10 = new Isaac10("your-subdomain");

All API functions are called on this object and return a Promise which passes the JSON response of the API call to success and failure.

Authentication

POST /api/v1/authenticate HTTP/1.1

{
  "email": "you@example.com",
  "password": "customer password"
}

isaac10.login('email', 'password');

{
  "success": {
    "customer_number": "100001",
    "customer_token":  "abc123",
    "confirmed":        true
  }
}

{
  "success": {
    ...
    "confirmed":                 false,
    "request_confirmation_url": "http://subdomain.isaac10.com/confirm/789"
  }
}

If you wish to outsource the customer authentication entirely to isaac10, you can request customer number and customer token, which are needed for the AUTHORIZE header or the JavaScript function .authenticateCustomer() (explained in Customer Authentication), with this API call.

If you are using the JavaScript library, .authenticateCustomer() will be called automatically with the returned customer number and customer token after the request returns successfully.

Params

Parameter	Description
email	Email address of the customer. required
password	Password of the customer. required

If email and password are not matching, error 404 will be returned.

Response

Parameter	Description
customer_number customer_token	Customer number and customer token to be used for Customer Authentication.
confirmed	Is the customer confirmed (i.e. clicked on the confirmation link send to her/him after the registration)? `true` or `false`.
request_confirmation_url	Only present when the customer is not confirmed. A GET request to this URL will trigger sending an email with the confirmation link to the customer.

Customer Authentication

For using the functions regarding customer specific data, the customer has to be authenticated. The data required for authentication of the customer (API token, customer number) after a register request are returned as customer_token and customer_number and have to be stored in your system.

If you wish to outsource the authentication process entirely to our isaac10 system, you need to embed the API call authenticate - login of customer, returning token and customer number.

REST API

GET /api/v1/... HTTP/1.1
Authorization: Token token="<customer_token>"

If a request requires the authentication of the customer, the customer’s API token has to be sent within the Authorization Header. The customer number, as part of the URL, has to be transferred as well.

JavaScript API

isaac10.authenticateCustomer("<customer_number>", "<customer_token>");

When using the JavaScript API the customer has to be authenticated before his first request of a protected function by using his customer number and his API token. The authentication itself works by the method .authenticateCustomer() with an instance of the isaac10 object. (shown right)

The request authenticateCustomer() itself won’t create a HTTP request. The client’s customer number as well as the customer token gets stored in the isaac10 object and returned (if necessary) with every request.

console.log(isaac10.customerNumber);
// => "<customer_number>"`

console.log(isaac10.customerApiToken);
// => "<customer_api_token>"`

Once customer number and API token of the customer set, they can be displayed as properties of the isaac10 object. (shown right)

Merchant Authentication

In order to use the merchant’s functions you have to authenticate with the system using your merchant API token. To find your merchant API token, see the merchant backend under the following section:

Konfiguration > Allgemeine Einstellungen

REST API

GET /api/v1/... HTTP/1.1
Authorization: Token token="<merchant_token>"

If a request requires the authentication of the merchant, the merchant’s API token has to be transferred within the Authorization header.

JavaScript API

isaac10.authenticateMerchant('merchant_token');

console.log(isaac10.merchantToken);
// => "merchant_token"

When using the JavaScript API you have to authenticate yourself before your first request of a protected function by using your merchant API token. The authentication itself works by the method authenticateMerchant() with an instance of the isaac10 object. (shown right)

Like the equivalent function for the customer, the request authenticateMerchant() won’t create a HTTP request. The merchant’s API token gets stored in the isaac10 object and returned (if necessary) with every request.

Public Functions

getProducts - Retrieving of Product and Plan Data

GET /api/v1/products HTTP/1.1

isaac10.getProducts();

{
  "products": [
    {
      "product_name 1": {
        "internal_product_name": "internal_product_name",
        "plans": [
          {
            "plan_name 1": {
              "nid": "NID Tarif 1",
              "price": [
                {
                  "interval": "monthly",
                  "cents": 0
                },
                {
                  "interval": "quarterly",
                  "cents": 0
                },
                {
                  "interval": "yearly",
                  "cents": 0
                }
              ],
              "setup_fee": null,
              "data": ""
            }
          },
          {
            "plan_name 2": {
              "nid": "NID Tarif 2",
              "price": [],
              "setup_fee": null,
              "data": null
            }
          },
          {
            "plan_name 3": {
              "nid": "NID Tarif 3",
              "price": [
                {
                  "interval": "monthly",
                  "cents": 2000
                }
              ],
              "setup_fee": 500,
              "data": null
            }
          }
        ]
      }
    },
    {
      "product_name 2": {
        ...
      }
    }
  ]
}

This function can be used to display project data on websites. If there’s no products set on the subdomain, an empty array with status 200 will be returned.

Call API Token of external Payment Service Providers

GET /api/v1/api_token HTTP/1.1

console.log(isaac10.apiToken);
// => { "notLoaded": true }

isaac10.withApiToken().then(function() {
  console.log(isaac10.apiToken);
  // => {
  //      "sandbox_mode":          true,
  //      "betterpayment_api_key": "123abc",
  //    }
});

{
  "api_token": {
     "sandbox_mode":          "true",
     "betterpayment_api_key": "123abc"
   }
 }

To be able to use external payment service providers (PSPs) within the system, you need to configure your merchant account by displaying their public API tokens. Those public API tokens can be called by this request.

Customer Registration

Customer registration is done in four steps:

Request the plan data to receive all data that is needed to display the registration form.
(optional) When the customer entered a coupon code, you may check if the entered coupon code is valid.
Register the customer by submitting the entered data for the customer account, subscription, billing address and payment information.
Confirm the subscription of the customer. This step is mandatory. As long as a subscription is not confirmed, it will not show up in your subscription overview and will not be accessible.

Request Plan Data

GET /api/v1/register/plan_nid HTTP/1.1

isaac10.getPlan('plan_nid');

{
  "plan": {
    "nid": "<plan_nid>",
    "product_name": "name of the product",
    "internal_product_name": "internal name of the product",
    "plan_name": "name of the plan",
    "public": true,
    "logo_url": "http://path/to/merchant/logo.png",

    "imprint_url_de": "http://example.com/imprint_de",
    "terms_of_use_url_de": "http://example.com/terms_of_use_de",
    "privacy_notice_url_de": "http://example.com/privacy_notice_de",
    "withdrawal_notice_url_de": "http://example.com/withdrawal_notice_de",
    "imprint_url_en": "http://example.com/imprint_en",
    "terms_of_use_url_en": "http://example.com/terms_of_use_en",
    "privacy_notice_url_en": "http://example.com/privacy_notice_en",
    "withdrawal_notice_url_en": "http://example.com/withdrawal_notice_en",

    "success_redirect_url": "",
    "instant_redirect": false,

    "pricing": "brutto",
    "price": [
      { "interval": "monthly", "cents": 1000 },
      { "interval": "quarterly", "cents": 3000 },
      { "interval": "yearly", "cents": 12000 }
    ],
    "setup_fee": 500,
    "currency": "EUR",

    "data": "Your API data you entered in the product configration",

    "always_ask_for_billing_and_payment_data": false,

    "vat_b2c": [
      { "country": "DE", "percent": "19.0" },
      { "country": "CH", "percent": "11.0" },
      { "country": "BE", "percent": "19.0" }
    ],

    "vat_b2c": [
      { "country": "DE", "percent": "19.0" },
      { "country": "CH", "percent": "11.0" },
      { "country": "BE", "percent": "19.0" }
    ],
    "merchant_country": "DE",

    "additions": [
      {
        "nid": "NID of addition 1",
        "name": "name of addition 1",
        "price": [
          { "interval": "monthly", "cents": 100 },
          { "interval": "quarterly", "cents": 300 },
          { "interval": "yearly", "cents": 1200 }
        ],
        "quantifiable": false
      },
      {
        "nid": "NID of addition 2",
        "name": "name of addition 2",
        "price": [
          { "interval": "monthly", "cents": 200 },
          { "interval": "quarterly", "cents": 600 },
          { "interval": "yearly", "cents": 2400 }
        ],
        "quantifiable": true
      }
    ],
    "payment_data_logos": ["visa", "mastercard"],
    "payment_data_types": ["invoice", "elv_dtaus"]
  }
}

Request the data necessary to display the registration form.

Params

Parameter	Description
plan_nid (in URL)	The NID of the plan

Response

Parameter	Description
vat_b2b	This key is only included when a B2B VAT list is assigned to the product of the plan.

Verification of Coupon Code

GET /api/v1/register/coupons/coupon_code?plan=plan_nid HTTP/1.1

isaac10.checkCouponCode(coupon_code, {"plan_nid": "<plan_nid>" });

{
 "coupon":
 {
   "coupon_code": "<coupon_code>",
   "cents": 1200,
   "message": "Erfolgsmeldung des Gutscheins"
 }
}

Params

Parameter	Description
coupon_code	Code of the coupon
plan_nid	NID of the plan

Register

POST /api/v1/register HTTP/1.1

isaac10.register(params);

{
  "register": {
    "plan_nid": "NID of the plan",
    "billing_interval": "yearly",

    "gender": "female",
    "title": "Dr.",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "company": "Company",
    "street": "Street 42",
    "zip": "12345",
    "city": "City",
    "country": "DE",
    "ustid": "",

    "payment_method": "invoice",

    "additions": [
      { "nid": "NID addition 1", "quantity": 1 },
      { "nid": "NID addition 2", "quantity": 4 }
    ],

    "coupon_code": "",

    "email": "email@example.com",
    "password": "password",

    "locale": "de"
  }
}

Parameters

Parameter	Description
plan_nid	The NID of the plan. required plan must exist for this merchant plan must be enabled
billing_interval	The billing interval for the subscription. required if plan is with costs allowed values: `"monthly", "quarterly", "yearly"`
additions	Additions for the plan. all additions must be related to the booked plan itself
gender	Gender of the subscribing customer. required, when plan is with costs allowed values: male, female
first_name	First name of the customer. required, when plan is with costs
last_name	Last name of the customer. required, when plan is with costs
street	Street name of the customer’s address. required, when plan is with costs
zip	Zip code of the customer’s address. required, when plan is with costs
city	City of the customer’s address. required, when plan is with costs
country	Name of the country of the customer’s address. required, when plan is with costs must be a double-digit country code must be included in the tax list
payment_method	The payment method to use. The example shows `invoice`. For all payment methods and the instructions to integrate them, see Payment Methods required if plan is with costs for allowed values see Payment Methods
coupon_code	Code number of the coupon. optional if coupon code is transferred, must be valuable and activated
email	Mail adress of the customer. required has to contain the `@` character must not have already been assigned to this subdomain or this merchant
password	Customer’s password for Login. required must contain at least 6 characters
locale	The language of the customer. optional (default: `"de"`) allowed values: `"de", "en", "fr", "it", "es"`, depending on the languages enabled in the merchant backend (Settings > Language Settings / Konfiguration > Spracheinstellungen) When used in the JavaScript library and locale is not passed, the transmitted locale of the browser is used.

Response

{
  "customer_number": "000001",
  "customer_token": "abc123",
  "plan_nid": "abc123",
  "subscription_id": 42
}

Parameter	Description
customer_number, customer_token	The customer number and customer token of the newly created account. Unless you want to use the login function of isaac10 for authenticating your users, you need to save these in your database for authenticating your customers.
plan_nid	The NID of the subscribed plan.
subscription_id	The ID of the newly created subscription. You need it as a parameter for confirming the subscription.

Confirmation after Registration

GET /api/v1/customer/<customer_nmber>/thank_you/<subscription_id>/register?double_opt_in=true HTTP/1.1

isaac10.thankYouAfterRegister(subscription_id, { double_opt_in: true });

{
  "plan": {
    ...
  },
  "subscription": {
    "id": "42",
    "product_name": "name of the product",
    "internal_product_name": "internal name of the product",
    "plan_name": "name of the plan",
    "begins_at": "2015-08-19",
    "term_ends_at": "2015-09-18",
    "billing_interval": "monthly",
    "next_billing_interval": "monthly",
    "status": "ongoing",
    "currency": "EUR",
    "price": [
      { "interval": "monthly", "cents": 1000 },
      { "interval": "quarterly", "cents": 3000 },
      { "interval": "yearly", "cents": 12000 }
    ],
    "additions": [
      ...
    ]
  }
}

Params

Parameter	Description
customer_number (REST only)	Number identifying the customer.
subscription_id	ID of the subscription.
double_opt_in	Should a mail with a confirmation link be sent to the customer? `true` or `false` (optional, default: `true`)

Using this function, the transmission of the email informing the merchant about a new customer/new subscription as well as of the subscription confirmation email for the customer gets initiated. Therefore by using the double_opt_in it must be decided, whether an email for the customer is sent out or not.

Every of the following functions register - Customer registration, Adding a new Subscription and Upgrading/Downgrading create a new data record for a subscription, not yet been confirmed. The ID of this subscription created will be used within the “thank you” functions, in order to confirm the newly created record. Consequently calling the “thank you” functions isn’t optional.

All kind of emails for new registrations, double-opt-in and downgrade confirmations will also be initiated by the “thank you” functions.

Response

Parameter	Description
plan	This data is the same as returned by Request Plan Data
subscription	The confirmed subscription.
subscription.product_name	The name of the product.
subscription.internal_product_name	The internal name of the product.
subscription.plan_name	The name of the plan.
subscription.begins_at	The date when the subscription started. Since this is the response for a new registration, it will be today.
subscription.term_ends_at	The date when this term (= the first term) ends.
subscription.billing_interval	The chosen billing interval.
subscription.next_billing_interval	The billing interval after this term ends. Since this is the response for a new registration, it will be the same as the billing interval.
subscription.status	See List Customer Subscriptions. Since this is the response for a new registration, it will be `ongoing`.
subscription.currency	The currency.
subscription.price	The prices for the possible billing intervals.
additions	The subscribed additions.

Subscription Management

List Customer Subscriptions

GET /api/v1/customer/customer_number/subscriptions HTTP/1.1

isaac10.getSubscriptions();

{
  "subscriptions": [
    {
      "id":                     42,
      "product_name":          "name of the product",
      "internal_product_name": "internal name of the product",
      "plan_name":             "name of the plan",
      "plan_nid":              "abc123",
      "begins_at":             "2014-09-25",
      "term_ends_at":          "2014-10-24",
      "billing_interval":      "monthly",
      "next_billing_interval": "monthly",
      "status":                "ongoing",
      "currency":              "EUR",
      "pricing":               "brutto",
      "price":                  3000,
      "next_price":             3000,

      "additions": [
        {
          "nid":               "NID of the addition",
          "name":              "name of the addition",
          "begins_at":         "2014-09-25",
          "price":              200,
          "next_price":         200,
          "quantifiable":       true,
          "quantity":           2,
          "next_quantity":      1
        }, {
          ...
        }
      ],

      "total_price":            3400,
      "next_total_price":       3200
    }, {
      ...
    }
  ]
}

Params

Parameter	Description
customer_number (in URL)	The ID of the customer.

Response

An array of all subscriptions of the customer.

Parameter	Description
begins_at	The date when the subscription started.
term_ends_at	The date when the current term of the subscription ends.
billing_interval	The billing interval the customer has choosen for the current term: `monthly`, `quarterly` or `yearly`.
next_billing_interval	The billing interval that gets valid when the next term starts: `monthly`, `quarterly` or `yearly`.
status	see table below
pricing	Are prices gross or net? `brutto` for gross, `netto` for net (yes, these are the german terms).
price	Indication in cents for the current term of the subscription without additions.
next_price	Indication in cents for the next term of the subscription without additions.
additions[]	An array of all subscribed additions.
additions[].begins_at	The date when the addition was booked.
additions[].price	Indication in cents of the addition for the current term.
additions[].next_price	Indication in cents of the addition for the next term.
additions[].quantifiable	Is the addition quantifiable? `true` or `false`.
additions[].quantity	The subscribed quantity of the addition for the current term. Always `1` when the addition is not quantifiable.
additions[].next_quantity	The quantity of the addition for the next term. When `0` the addition will be canceled when the end of the term is reached.
total_price	Indication in cents for the current term of the subscription including additions.
next_total_price	Indication if cents for the next term of the subscription including additions.

status

Value	Description
`ongoing`	Subscription is active and not in cancellation
`canceled`	Subscription is canceled, end of contract not reached yet
`expired`	Subscription is canceled, end of the contract is reached
`future`	Subscription contract starts in the future

Call Customer and Plan data

GET /api/v1/customer/customer_number/subscriptions/new?plan=plan_nid HTTP/1.1

isaac10.getSubscribe(plan_nid);

{
  "plan": {

  },
  "account": {

  }
}

Params

Parameter	Description
customer_number (in URL)	The ID of the customer.
plan_nid	The NID of the plan.

Account data of the customer and plan data can be called up in the same request.

Response

Parameter	Description
plan	This data is the same as provided when calling `.getPlan()`.
account	This data is the same as provided when calling `.getAccount()`.

Edit a Subscription

Retrieve all necessary data to display an edit form for the subscription with the given subscription_id and a table with all possible up- and downgrade options.

GET /api/v1/customer/<customer_number>/subscriptions/<subscription_id>/edit HTTP/1.1

isaac10.editSubscription(subscription_id);

{
  "plan": {
    ...
  },
  "billing_data": {
    ...
  },
  "payment_data": {
    ...
  },
  "subscription": {
    "id":                     42,
    "product_name":          "name of the product",
    "internal_product_name": "internal name of the product",
    "plan_name":             "name of the plan",
    "begins_at":             "2014-09-25",
    "term_ends_at":          "2014-10-24",
    "billing_interval":      "monthly",
    "next_billing_interval": "monthly",
    "status":                "ongoing",
    "currency":              "EUR",
    "pricing":               "brutto",

    "price": [
      { "interval": "monthly", "cents":  3000 },
      { "interval": "yearly",  "cents": 36000 }
    ],

    "additions": [
      {
        "nid":               "NID of the addition",
        "name":              "name of the addition",
        "begins_at":         "2014-09-25",
        "quantifiable":       true,
        "quantity":           2,
        "next_quantity":      1,

        "price": [
          { "interval": "monthly", "cents":  1000 },
          { "interval": "yearly",  "cents": 12000 }
        ]
      }, {
        ...
      }
    ]
  },
  "allowed_transitions": [
    {
      "nid": "NID of the current plan",
      "name": "Name of the current plan",
      "transition_type": "self"
    }, {
      "nid": "NID of another plan",
      "name": "Name of another plan",
      "transition_type": "upgrade"
    }, {
      "nid": "NID of another plan",
      "name": "Name of another plan",
      "transition_type": "downgrade"
    }, {
      ...
    }
  ]
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id (in URL)	The ID of the subscription.

Response

Parameter	Description
plan	Data of the plan. Same as Request Plan Data
billing_data	Data of the customer’s billing address. Same as Get Account Data
payment_data	Data of the given payment method. Same as Get Account Data
subscription	Data of the subscription to edit.
subscription.begins_at subscription.term_ends_at subscription.billing_interval subscription.next_billing_interval subscription.status subscription.pricing	Same as Get Subscriptions
subscription.price	The prices for the possible billing intervals.
subscription.additions[]	An array of all additions, both subscribed and unsubscribed.
subscription.additions[].begins_at	The date when the addition was booked. Is `null` when the addition is not booked.
subscription.additions[].quantifiable	Is the addition quantifiable? `true` or `false`.
subscription.additions[].quantity	The subscribed quantity of the addition for the current term. Is `0` when the addition is not subscribed. Is `1` when the addition is subscribed and not quantifiable.
subscription.additions[].next_quantity	The quantity of the addition for the next term. When `0` the addition is either unsubscribed or will be canceled when the end of the term is reached.
subscription.additions[].price	The prices for the possible billing intervals of the addition. The allowed billing intervals will match those of the subscription itself (see above).
allowed_transitions[]	Additional information for Upgrading/Downgrading. The table includes all possible plans for up- and downgrading the subscription.
allowed_transitions[].nid	The NID of the plan to which can be up- or downgraded.
allowed_transitions[].name	The name of the plan to which can be up- or downgraded.
allowed_transitions[].transition_type	See table below

transition_type

Value	Description
`upgrade`	Changing the subscription to this plan will be considered an upgrade and therefore will be valid immediately.
`downgrade`	Changing the subscriptio to this plan will be considered a downgrade and therefore will be valid when the end of the current term is reached.
`self`	The current plan. Listed in the array for convenience reasons.

Why there are duplicate price arrays?

The response contains prices from the plan (in plan.price and plan.additions[].price) and the subscription (in subscription.price and subscription.additions[].price). These prices may differ since you as merchant can override the prices set in the plan in any specific subscription and addition of a customer.

If an addition is not subscribed, it will always show the prices defined in the plan.

Call of Account, Subscription and Plan Data

GET /api/v1/customer/customer_number/subscriptions/subscription_id/upgrade_downgrade/plan_nid HTTP/1.1

isaac10.getUpgradeDowngradeSubscription(subscription_id, plan_nid);

{
  "plan": {
  },
  "account": {
  },
  "subscription": {
    "id": "6",
    "begins_at": "2015-09-21",
    "term_ends_at": "2015-10-20",
    "billing_interval": "monthly",
    "next_billing_interval": "monthly",
    "status": "ongoing",
    "additions": []
  }
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.
plan_nid	The NID of the plan.

Response

Parameter	Description
plan	This data is the same as provided when calling `.getPlan()`.
account	This data is the same as provided when calling `.getAccount()`.
subscription	Data of the created subscription.

Updating a Subscription

PATCH /api/v1/customer/customer_number/subscriptions/subscription_id HTTP/1.1

isaac10.updateSubscription(subscription_id, params);

{
  "subscription": {
    "billing_interval": "yearly",
    "additions": [
      { "nid": "NID Tarifergänzung 1", "quantity": "1" },
      { "nid": "NID Tarifergänzung 2", "quantity": "0" },
      { "nid": "NID Tarifergänzung 3", "quantity": "2" }
    ]
  }
}

{
  "success": true
}

Change a subscription of a customer. All changes are saved (when valid), but not all take effect immediately.

Changes that take effect immediately

Raising the quantity of an addition
Adding an addition (i.e. raising the quantity of a non-subscribed addition above 0)

Changes that take effect when the next term starts

Changing the billing interval
Lowering the quantity of an addition
Cancelation of an addition (i.e. lowering the quantity of a subscribed addition to 0)

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id (in URL)	The ID of the subscription.
billing_interval	The period of billing, offered by the merchant. required possible values: `monthly`, `quarterly`, `yearly` The billing interval must be enabled for the subscription (See also: Enabled billing intervals)
additions	The addition for a plan. an addition with the given nid must exist for the plan to be changed quantify must be a natural number

Upgrading/Downgrading a Subscription

POST /api/v1/customer/customer_number/subscriptions/subscription_id/upgrade_downgrade HTTP/1.1

isaac10.upgradeDowngradeSubscription(subscription_id, params);

"subscription": {
  "plan_nid": "NID of the plan",
  "billing_interval": "monthly",
  "additions": [
    { "nid": "NID addition 1", "quantity": 1 },
    { "nid": "NID addition 2", "quantity": 4 },
  ]
}

"subscription": {
  "plan_nid": "NID of the plan",
  "billing_interval": "monthly",
  "additions": [
    { "nid": "NID addition 1", "quantity": 1 },
    { "nid": "NID addition 2", "quantity": 4 },
  ],
  "gender":           "female",
  "title":            "",
  "first_name":       "Maxi",
  "last_name":        "Mustermann",
  "company":          "",
  "street":           "Musterstraße 1",
  "zip":              "12345",
  "city":             "Musterstadt",
  "country":          "DE",
  "ustid":            "",

  "payment_method": "invoice"
}

{
  "success": {
    "subscription_id": 3793
  }
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.

Validations

The validations and conditions for an upgrade/downgrade are the same as mentioned in chapter Adding a new Subscription.

The conditions for billing address and billing method as mentioned below are the same for this call and, if necessary, must be transferred.

Confirmation after Upgrade/Downgrade

GET /api/v1/customer/customer_number/thank_you/subscription_id/upgrade_downgrade HTTP/1.1

isaac10.thankYouAfterUpgradeDowngrade(subscription_id);

{
  "plan": {
  },
  "subscription": {
}
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.

Response

Parameter	Description
plan	This data is the same as provided when calling `.getPlan()`.
subscription	This Data is the same as provided when calling `.thankYouAfterRegister()`.

As described in Confirmation after Registration the function Upgrading/Downgrading a Subscription creates a new data record for a subscription, not yet been confirmed. The created ID of this subscription will be used here, in order to confirm the newly created record.

Adding a new Subscription

POST /api/v1/customer/customer_number/subscriptions HTTP/1.1

isaac10.addSubscription(params);

{
  "id": null,
  "subscription": {
    "plan_nid": "NID of the plan",
    "billing_interval": "monthly",
    "additions": [
      { "nid": "NID addition 1", "quantity": 1 },
      { "nid": "NID addition 2", "quantity": 4 },
    ]
  }
}

{
  "id": null,
  "subscription": {
    "plan_nid": "NID of the plan",
    "billing_interval": "monthly",
    "additions": [
      { "nid": "NID addition 1", "quantity": 1 },
      { "nid": "NID addition 2", "quantity": 4 },
    ],

    "gender":           "female",
    "title":            "",
    "first_name":       "Maxi",
    "last_name":        "Mustermann",
    "company":          "",
    "street":           "Musterstraße 1",
    "zip":              "12345",
    "city":             "Musterstadt",
    "country":          "DE",
    "ustid":            "",

    "payment_method": "invoice"
  }
}

{
  "plan": {
  },
  "subscription": {
}
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

If the plan is with costs and neither billing address nor paymemt method have been given by the customer, the following data has to be transmitted for the subscription of the plan. (see right side)

Validation

Parameter	Description
plan_nid	The NID of the plan. required plan must exist for this merchant plan must be enabled
billing_interval	The billing interval for the subscription. required if plan is with costs allowed values: monthly, quarterly, yearly
additions	Additions for the plan. all additions must be related to the booked plan itself
gender	Gender of the subscribing customer. required, when plan is with costs allowed values: male, female
first_name	First name of the customer. required, when plan is with costs
last_name	Last name of the customer. required, when plan is with costs
street	Street name of the customer’s address. required, when plan is with costs
zip	Zip code of the customer’s address. required, when plan is with costs
city	City of the customer’s address. required, when plan is with costs
country	Name of the country of the customer’s address. required, when plan is with costs must be a double-digit country code must be included in the tax list
payment_method	The payment method to use. The example shows `invoice`. For all payment methods and the instructions to integrate them, see Payment Methods. required if plan is with costs for allowed values see Payment Methods

Confirmation after Subscription

GET /api/v1/customer/customer_number/thank_you/subscription_id/add HTTP/1.1

isaac10.thankYouAfterAdd(subscription_id);

{
  "plan": {
  },
  "subscription": {
  }
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.

Response

Parameter	Description
plan	This data is the same as provided when calling `.getPlan()`.
subscription	This Data is the same as provided when calling `.thankYouAfterRegister()`.

As described in Confirmation after Registration the function Adding a new Subscription creates a new data record for a subscription, not yet been confirmed. The created ID of this subscription will be used here, in order to confirm the newly created record.

Modify Subscription

The modification of a subscription is identical to Adding a new Subscription. isaac10 verifies if a subscription for this product is already existing for the customer.

When upgrading, the plan modification becomes effective immediately whereas when downgrading the plan modification just starts at the end of the respective contract period.

cancelSubscription - Cancel a Subscription

DELETE /api/v1/customer/customer_number/subscriptions/subscription_id HTTP/1.1

isaac10.cancelSubscription(subscription_id);

{
  "success": true
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.

uncancelSubscription - Uncancel a Subscription

DELETE /api/v1/customer/customer_number/subscriptions/subscription_id/revert HTTP/1.1

isaac10.uncancelSubscription(subscription_id);

{
  "success": true
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
subscription_id	The ID of the subscription.

Account functions

Get Customer Account Data

GET /api/v1/customer/<customer_number>/account HTTP/1.1

isaac10.getAccount();

{
  "account": {
    "account_data": {
      "email":           "email@example.com"
    },

    "billing_data": {
      "gender":          "female",
      "title":           "",
      "first_name":      "Maxi",
      "last_name":       "Mustermann",
      "company":         "Company",
      "addition":        "Accounts Department",
      "street":          "Musterstraße 1",
      "zip":             "12345",
      "city":            "Musterstadt",
      "country":         "DE",
      "ustid":           "DE1234567890"
    },

    "payment_data": {
      "payment_method":  "invoice"
    },

    "payment_data_logos": ["visa", "mastercard"],
    "payment_data_types": ["invoice", "cc_paymill", "elv_paymill"]
  }
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Response

Parameter	Description
billing_data	The billing data of the customer. When no billing address present, the returned value is `"none"`.
payment_data	Specific data requested according to the method chosen. When returned it will always contain a `payment_method` field. Further fields depend on the payment method used. See the Payment Methods chapter for further information. When no payment data present, the returned value is `"none"`.
payment_data_logos	Logos of the different types of payment methods: Visa Master Card American Express PayPal
payment_data_types	All possible payment methods of the merchant. Included for convenience reasons.

Updating the Customer’s Account Data

PATCH /api/v1/customer/customer_number/account/account_data HTTP/1.1

isaac10.updateAccountData(params);

{
  "account_data": {
    "email": "new_email@example.com"
  }
}

{
  "success": true
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Validation

Parameter	Description
email	The Email Address of the customer. required has to contain the @ character must not have already been assigned to this subdomain or this merchant

Updating the Customer’s Password

PATCH /api/v1/customer/customer_number/account/password HTTP/1.1

isaac10.updatePassword(params);

{
  "password": {
    "password": "new_password"
  }
}

{
  "success": true
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Validation

Parameter	Description
password	The new password of the customer. required must contain at least 6 characters

Updating the Customer’s Billing Address

PATCH /api/v1/customer/customer_number/account/billing_data HTTP/1.1

isaac10.updateBillingData(params);

{
  "billing_data": {
    "gender":          "female",
    "title":           "",
    "first_name":      "Vorname",
    "last_name":       "Nachname",
    "company":         "",
    "street":          "Musterstraße 1",
    "zip":             "12345",
    "city":            "Musterstadt",
    "ustid":           "DE1234567890"
  }
}

{
  "success": true
}

Update the billing address of the passed customer. When the customer has no billing address, it will be created. However, the returned status code is 200 in both cases.

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Validation

Parameter	Description
gender	The gender of the customer. required allowed values: `male`, `female`
first_name	The first name of the customer. required
last_name	The last name of the customer. required
street	The street of the customer’s billing address. required
zip	The zip code of the customer’s billing address. required
city	The city of the customer’s billing address. required

Updating the Customer’s Payment Method

PATCH /api/v1/customer/customer_number/account/billing_data HTTP/1.1

isaac10.updatePaymentData(params);

{
  "payment_data": {
    "payment_method": "invoice"
  }
}

{
  "success": true
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Validation

Parameter	Description
payment_method	The payment method chosen by the customer. required allowed values: see Payment Methods

Billing

Calling the Customer’s Bills

GET /api/v1/customer/customer_number/bills HTTP/1.1

isaac10.getBills();

{
  "bills":
    [
      [
        {
          "type_name": "bill_cancelation",
          "bill_number": "0001/2015/X",
          "canceled_at": "2015-08-19",
          "cents": 2000,
          "currency": "EUR",
          "url": "http://url/to/bill"
        },
        {
          "type_name": "bill",
          "bill_number": "0001/2015",
          "billed_at": "2015-08-14",
          "cents": 2000,
          "currency": "EUR",
          "url": "http://url/to/bill"
        },
        {
          "type_name": "first_dunning",
          "bill_number": "0001/2015/1",
          "billed_at": "2015-08-19",
          "cents": 2500,
          "currency": "EUR",
          "url": "http://url/to/bill"
        },
        {
          "type_name": "first_dunning_cancelation",
          "bill_number": "0001/2015/1/X",
          "canceled_at": "2015-08-19",
          "cents": 2500,
          "currency": "EUR",
          "url": "http://url/to/bill"
        }
      ]
    ]
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.

Response

Parameter	Description
type_name	The status of a bill or dunning. Possible types see below.
cents	Exposure the gross amount of an invoice in cents.
url	Contains the URL, displaying the download link for the bill. This is according to the API call Download of a PDF bill.

The field type_nameis according to the dunning level and other states a bill/dunning can have. Possible types are:

type_name	Description
bill	normal bill
first reminder second reminder	payment reminder
first_dunning second_dunning third_dunning	dunning
bill_cancelation first_dunning_cancelation second_dunning_cancelation third_dunning_cancelation	Cancelation of a bill or dunning

Please note
If the PDF file is not rendered yet, the returned hash won’t contain an url-key. This happens just in case, the customer opens this webpage briefly after the bill was released.

Download of a PDF Bill

GET /api/v1/customer/customer_number/bills/bill_slug/type_name HTTP/1.1

isaac10.downloadBill(url);

{
  "url": "https://..."
}

Params

Parameter	Description
customer_number (in URL)	The number identifying the customer.
bill_slug	Designation of the bill.
type_name	Type of the bill.

REST API

The return value contains a temporary URL for the PDF file. It’s validity is about one hour. A call of this temporary URL by a get request returns a bill as PDF file.

JavaScript API

The call of the JavaScript function by calling the REST API creates a temporary URL. Subsequently the bill as PDF file is downloading. The temporary URL won’t be returned.

Merchant functions

List all customers

GET /api/v1/customers HTTP/1.1

isaac10.getCustomers();

{
  "customers": [
    {
      "customer_number": "10001",
      "customer_token":  "abc123",

      "account": {
        ...
      },
      "subscriptions": [
        ...
      ]
    }
  ]
}

List all customers of the merchant. Customers without an ongoing subscription are included, but deleted customers (shown as “deleted” in the customer listing in the merchant backend) are not.

Response

Parameter	Description
customers	An array of all customers of the merchant.
customer_number customer_token	Customer number and customer token to be used for Customer Authentication.
account	The account data of the customer including billing address and payment data. See Get Customer Account Data.
subscriptions	All subscriptions of the customer. See List Customer Subscriptions.

Create a new customer

POST /api/v1/customers HTTP/1.1

// not implemented, REST only

{
  "customer": {
    "email":    "customer@example.com",
    "password": "password",
    "locale":   "de"
  }
}

{
  "success": {
    "customer_number": "100001",
    "customer_token":  "abc123"
  }
}

Create a new customer for the merchant. The created customer will not have a billing address, no payment information and no subscription. The customer is also created as confirmed (i.e. no double-opt-in) and can therefore log in immediately after it’s creation.

Params

Parameter	Description
email, password, locale	The email, password and locale for the new customer. See Register for further details.

Response

Parameter	Description
customer_number, customer_token	The customer number und customer token of the created customer.

Set customer custom data

PATCH /api/v1/customers/<customer_number>/custom_data HTTP/1.1

isaac10.setCustomerCustomData(customer_number, data);

Whatever you want. Please use responsibly, this is not a challenge.

{
  "success": true
}

You may set custom data for any of your customers. The data can be anything, there are no validations. It will be stored as-is in the database. To read the data see Get customer custom data.

Get customer custom data

GET /api/v1/customers/<customer_number>/custom_data HTTP/1.1

isaac10.getCustomerCustomData(customer_number);

Whatever you set at the customer. The content type "text/plain" is used.

Retrieve the data you set with Set customer custom data.

List bill clearance

GET /api/v1/bills HTTP/1.1

isaac10.getClearance();

{
  "bills": [
    {
      "id":                      123,
      "product_name":           "name of the product",
      "customer_number":        "100001",
      "currency":               "EUR",
      "brutto_amount":           11900,
      "netto_amount":            10000,
      "vat_amount":               1190,

      "bill_items": [
        {
          "invoice_text":       "the text appearing on the PDF invoice document",
          "brutto_base_amount":  4760,
          "netto_base_amount":   4000,
          "vat_base_amount":      760,
          "brutto_amount":       9520,
          "netto_amount":        8000,
          "vat_amount":          1520,
          "quantity":               2,
          "billed_from":        "2016-03-17",
          "billed_to":          "2016-04-16"
        },
        ...
      ]
    },
    ...
  ]
}

List all bills in the system that are not cleared. These appear in Bills > Clearance (german: Rechnungen > Rechnungsfreigabe) in the merchant backend. Please note that these bills do not have a bill number. The bill number is generated when a bill get’s cleared.

Clear bill

PATCH /api/v1/clearance/<bill_id> HTTP/1.1

isaac10.clearBill("bill_id");

{
  "success": true
}

Clears the bill with the given ID.

Params

Parameter	Description
bill_id	The ID of the bill to clear. Retrieve it by calling List Bill Clearance.

Creating an extra bill item

POST /api/v1/bill_items HTTP/1.1

isaac10.createBillItem(params);

{
  "bill_item": {
    "customer_number":       "100001",
    "internal_product_name": "internal product_name",
    "invoice_text":          "Text, being displayed on the bill",
    "amount_cents":          "2000",
    "quantity":              "1",
    "vat":                   "19.0",
    "billed_from":           "2015-03-12",
    "billed_to":             "2015-04-11"
  }
}

{
  "success": true
}

Validation

Parameter	Description
customer_number	required must exist and be one of your customers
internal_product_name	required must exist and be one of your products
invoice_text	required
amount_cents	required must be in form of a whole number
quantity	required must be in form of a whole number must be greater than zero
vat	required must be in form of a decimal number, containing a point as decimal separator must be greater than zero
billed_from	The start date of the bill item. required must be in form of a date according to ISO-8601 (YYYY-MM-DD)
billed_to	(optional) The end date of the bill item. When no end date is given, only the start date will be displayed on the bill. must be in form of a date according to ISO-8601 (YYYY-MM-DD) must lie after the `bill_from` date

How to create a credit item?

To create a credit item, just put a negative amount for amount_cents.

Payment Methods

Possible Payment Methods

isaac10 supports the following payment methods:

on invoice
direct debit (SEPA)
credit card
PayPal

The parameter payment_method specifies, which payment method gets stored. Each payment method requires different additional parameter.

Depending on the payment method chosen, the output also differs in payment_data when calling the customer’s data.

Invoice

{
  "payment_method": "invoice"
}

For payment upon invoicing no further specifications are necessary.

{
  "payment_data": {
    "payment_method": "invoice"
  }
}

Integration with JavaScript library

As payment on invoice doesn’t require further specifications, transferring the value invoice is sufficient.

Direct Debit (SEPA)

For the payment upon direct debit (SEPA) isaac10 offers two different methods:

integration of Micropayment: "payment_method": "elv_micropayment"
creation of SEPA-XML files, which you can deposit yourself at the bank: "payment_method": "elv_dtaus". This method is traditionally known as “garage clearing”.

{
  "payment_method": "elv_micropayment",
  "account_holder": "name of account holder",
  "iban": "the IBAN"
}

{
  "payment_data": {
    "payment_method": "elv_micropayment",
    "account_holder": "name of account holder",
    "iban": "the IBAN"
  }
}

{
  "payment_method": "elv_dtaus",
  "addr_name": "name of account holder",
  "bank_iban": "the IBAN"
}

{
  "payment_data": {
    "payment_method": "elv_dtaus",
    "account_holder": "name of account holder",
    "iban": "the IBAN"
  }
}

Params

Parameter	Description
account_holder or addr_name	required
iban or bank_iban	required must be an existing IBAN

Integration with JavaScript library

Account holder and IBAN can be called directly and be transferred to the respective JavaScript function. The transfer to Micropayment (elv_micropayment) will be made by isaac10 on the server side. Regarding SEPA-XML files (elv_dtaus), data will be stored by isaac10 itself.

Credit Card

For the payment by credit card isaac10 offers two different methods:

isaac10’s own integration: "payment_method": "cc_betterpayment". This is a white label solution provided by Better Payment
Micropayment integration: "payment_method": "cc_micropayment".

Payment by credit card with Micropayment is not yet implemented
This documentation is ahead of its time. The payment method cc_micropayment is scheduled for delivery in the next release.

A transfer of credit card information with the REST API is not possible for legal reasons. Credit card numbers must never be transferred to your or our servers. Therefore only a client side integration through an iframe, directly provided by the payment provider, is a possible solution. However, in case you did the client side integration of the iframe yourself, the returned tokens can be transferred to isaac10 through the REST API.

Request body for REST integration: `cc_betterpayment`

{
  "payment_method": "cc_betterpayment",
  "transaction_id": "transaction-ID of Better Payment"
}

To identify a payment transaction, Better Payment uses a transaction_id. Also the transfer of credit card information without immediate processing of a payment transaction (method used by isaac10) is treated in the same way. After a successful transfer of credit card information to Better Payment, the transaction_id can be sent over to isaac10.

Response: `cc_betterpayment`

{
  "payment_data": {
    "payment_method": "cc_betterpayment",
    "expire_month": "03",
    "expire_year": "15",
    "card_last4": "1234"
  }
}

Parameter	Description
expire_month and expire_year	The expiry date of the credit card.
card_last4	The last four digits of the credit card number.

Request body for REST integration: `cc_micropayment`

TODO

TODO

Response: `cc_micropayment`

TODO

TODO

Integration with JavaScript library

<!DOCTYPE html>
<html>
  <head>
    <script type="text/javascript">
      $(function() {
        function registerParams() {
          var params = {
            email: $('#email').val();
            /* all further data */
          };

          if ($('#payment_method_elv_micropayment:checked')) {
            $.extend(params, { payment_method: 'elv_micropayment',
                               account_holder: 'read value',
                               iban:           'read value' });
          } else if ($('payment_method_cc_betterpayment:checked')) {
            $.extend(params, { payment_method: 'cc_betterpayment' });
          }

          return params;
        }

        /*  initialize isaac10 library */
        var isaac10 = new Isaac10('my-subdomain');

        /* when payment with credit card is choosen: display iframe */
        $('#payment_method_cc_betterpayment').on('change', function() {
          if ($('#payment_method_cc_betterpayment:checked')) {
            isaac10.displayCreditCardiframe('#credit-card-iframe', 400, 300);
          }
        });

        /* when "Place Order" is clicked: send values to payment provider and
           isaac10 */
        $('#register-form').submit(function(event) {
          event.preventDefault();
          isaac10.register({register: registerParams()});
        });
      });
    </script>
  </head>
  <body>
    <h1>Register</h1>

    <!-- register file -->
    <form id="register-form">
    <input type="text" name="email" id="email" />
      <!-- ...and all further information requested -->

      <!-- radio buttons for choosing payment method -->
      <label for="payment_method_elv_micropayment">
        SEPA
        <input type="radio"
               name="payment_method"
               value="elv_micropayment"
               id="payment_method_elv_micropayment" />
      </label>
      <label for="payment_method_cc_betterpayment">
        credit card
        <input type="radio"
               name="payment_method"
               value="cc_betterpayment"
               id="payment_method_cc_betterpayment" />
      </label>

      <!-- iframe to transfer credit card data -->
      <div id="credit-card-iframe"></div>

      <!-- submit button for registration -->
      <button>Place Order</button>
    </form>
  </body>
</html>

The JavaScript library (in comparison to an own implementation) offers an easy integration into your front end. The procedure is the same for both, elv_betterpayment and elv_micropayment. Implementation procedure is as follows:

1. Place a <div> in the HTML code

where the iframe for the credit card form should be placed into.

2. Display the credit card iframe

by calling the function isaac10.displayCreditCardiframe(selector, width, height). The call and therefore the display can be linked to a JavaScript event, e.g. choosing a radio button.

selector is the jQuery selector for the <div>, where the iframe shall be rendered
width and height are the dimensions of the iframe

3. Transmit the credit card data

by calling one of the functions that transmit payment data to isaac10 (e.g. registration of a new customer with isaac10.register(...) or updating of payment data isaac10.updatePaymentData(...)). Pass "payment_method": "cc_betterpayment" or "payment_method": "cc_micropayment" as payment method in the params hash without any additional data. This can be linked to a JavaScript event too, e.g. clicking a button Place Order.

The JavaScript library identifies the payment method and understands that the iframe got loaded and the customer entered his payment data in the iframe. The transmission of the data to Better Payment/Micropayment and the processing of the return values is done internally in the library. Then the transmission of the payment data (and all further information, depending on the called function) to isaac10 will be executed.

The example on the right shows the use of the JavaScript library to build a registration page. Please note that it is only complete for credit card payment. There is a radio button for SEPA payment but the necessary text fields for IBAN and account holder are missing. We will provide a complete example soon.

PayPal

{
  "payment_method": "paypal"
}

{
  "payment_data": {
    "payment_method": "paypal"
  }
}

Params

For the payment with PayPal no further parameters (aside from "payment_method": "paypal") need to be passed.

However, when using the REST integration, you must pass special successURLs and failureURLs to the PayPal API to make PayPal send the billing agreement back to issac10 and not directly to your website. (Description TODO)

When using the JavaScript library, the billing agreement of PayPal is sent to isaac10 automatically. This is described below.

Setup in Merchant Configuration

The input mask for your PayPal ID (normally your email address with PayPal) and the display of given agreements on behalf of PayPal, as far as this payment method is activated for you, can be found in

Settings > Payment methods

Integration with JavaScript library

With our isaac10 JavaScript library you can call up the In-Context-Express-Checkout by what PayPal customers conclude a billing agreement with the merchant. This billing agreement will be maintained in the background by isaac10 in order to use it for further debiting.

Please follow these steps:

1. Call a function which transfers the payment data

e.g. .register() or .updatePaymentData() and pass "payment_method": "paypal" in the params.

2. In case of registration: Authenticate the customer

by using the customer number and customer token received by step 1. This is unnecessary if you changed the payment data of an existing customer. The authentication must have been already done in this case (otherwise you could not have called the function for changing the payment data in the first place).

3. Call the function to process PayPal

which is named .processPaypal(successURL, failureURL).

successURL: PayPal redirects to this URL in case the customer confirms the payment via PayPal.
failureURL: PayPal redirects to this URL in case the customer cancels the payment via PayPal.

After the call the express checkout window by PayPal will open which redirects the customer to PayPal. Please keep in mind that you have to call the subscription confirmation (Confirmation after Registration, Confirmation after Upgrade/Downgrade or Confirmation after Subscription) when the successURL is opened.

isaac10 UI

Embedding and Initialization

<script type="text/javascript" src="https://app.isaac10.com/api/v1/isaac10_api.js"></script>
<script type="text/javascript" src="https://app.isaac10.com/ui/isaac10_ui.js"></script>

<script type="text/javascript">
  // Initialization of JavaScript API
  var isaac10 = new Isaac10("your-subdomain");

  // Initialization of isaac10 UI
  isaac10UI.setup({
    "isaac10Instance": isaac10,
    "fetchTemplate":  "bootstrap3",
    "locale":         "de"
  }).render("#isaac10-ui");
</script>

<div id="isaac10-ui"></div>

To be able to use the isaac10 UI, the JavaScript library of isaac10 must be loaded as well. See right side, for how to initialize the isaac10 UI and render it on your website.

Configuration

Parameter	Description	Possible Values
isaac10Instance		An instance of the `Isaac10` object.
fetchTemplate	the HTML templates (or handlebar templates) to be loaded	`false` (no templates will be loaded, you have to provide the templates yourself) `"bootstrap3"`
overrideTranslations	See Overwriting and Adding Translations	A JavaScript object, structured like a translation file.
locale	The language that should be used in the isaac10 UI	`"de"` (german) `"en"` (english) More languages can be added through the overrideTranslations parameter.

Display the isaac10-UI

The call of .render() rendered the isaac10 UI in the HTML element, referenced by the passed jQuery selector (as shown in the given example: the element with ID #isaac10-ui). The element should be a <div> tag but can be anything else.

Navigating through the isaac10-UI

The page to be displayed is controlled by an URL anchor. If the isaac10 UI is rendered on a page with an URL without anchor, only a test page will be displayed, stating: isaac10-UI works!

The following pages are available:

the Registration Page for new Customers
Overview and forms for account data
bills overview
subscriptions overview and forms to have the subscriptions managed

More pages can be reached by clicking on the links on these pages.

Customer specific Pages

isaac10.authenticateCustomer("<customer_number>", "<customer_token>");

To display the pages and forms involving account-, billing- and subscription-data the customer need to get authenticated via the JavaScript-API (see Javascript tab).

You receive the parameter customer_number and customer_token with the form on Registration Page for new Customers (or alternatively by Register a Customer via API).

URL anchors

Called Page	Anchor
account data	#/account
billing data	#/bills
subscription data	#/subscriptions

Registration Page for new Customers

URL anchor

#/plan/plan_nid

Params

Parameter	Description
plan_nid	The NID of the plan.

Transfer Data to your System

Please go to your merchant-backend

Settings > Integration settings

This area offers you options to modify the register webhooks. You can chose a HTTP method (GET/POST) and enter an URL. By completing a new registration successfully the data will be transferred to the configured URL using the chosen HTTP-method.

Please file the values of customer_number und customer_api_token in your system. They are needed to authenticate the customer and therefore to display the overview pages.

Overwriting and Adding Translations

// your translations
var customTranslations = {
  "de": {
    "defaults": {
      "save": "send"
    }
  }
};

// Initializing the JavaScript API
var isaac10 = new Isaac10("ihre-subdomain");

// Initializing the isaac10UI
Isaac10UI.setup({
  "isaac10Instance": isaac10,
  "fetchTemplate": "bootstrap3",
  "locale": "de",
  "overrideTranslations": customTranslations   // <--------------------
}).render("#isaac10-ui");

By initializing the isaac10 UI you can overwrite or add translations employing the parameter overrideTranslations. Therefore you need to generate a JavaScript object which has the same structure as the translation file (see JavaScript tab).

You can use the currently used translation file in not minified form (as coffee script) as template to be downloaded here:

https://app.isaac10.com/ui/translations.coffee

Apply custom Templates

<script type="text/x-handlebars"
        data-template-name="isaac10-ui/components/div-accountDataFields">
  // Embed the handlebars template for the account data fields component here.
  //
  // The component used when fetching the Bootstrap 3 templates is shown below
  // as an example.
</script>

{{! isaac10-ui/components/div-accountDataFields}}

<div class="{{if errors.email 'has-error'}}">
  <label for="emailField">
    {{t 'components.divAccountDataFields.emailLabel'}}
  </label>
  {{input type="text" value=email id="emailField"}}
  {{#if errors.email}}
    <div class="error">{{errors.email}}</div>
  {{/if}}
</div>

You also can integrate the isaac10 UI forms as blank pages in case you prefer to use your own templates. Therefore you must initiate the isaac10 UI with fetchTemplate: false. As a result none of the templates will be reloaded and forms will be rendered to the given HTML element which has to contain the handlebars elements. These elements need to have the format to be seen on the right side.

Some CSS classes are already implicated (like 'has-error‘). All elements can easily be modified with own CSS classes e.g. for validation failure for the foundation CSS framework (see right side).

Additional information

Enabled billing intervals

isaac10 offers three billing intervals:

monthly
quarterly
yearly

Not all billing intervals are available at all times. A billing interval is enabled when there is a price defined for that billing interval:

When registering a new customer, adding a new subscription or upgrading/downgrading a subscription, the billing interval must be enabled on the plan that should be subscribed.
When updating a subscription, the billing interval must be enabled on the subscription you are about to update. There may be billing intervals available for a specific subscription that are not available for it’s plan and vice versa as you, as a merchant, can edit a subscription in you merchant backend and add or remove prices for the subscription. This alters the enabled billing intervals for the subscription without altering the plan.

isaac10 API Documentation

Overview

Hosted Pages

REST API

JavaScript API

isaac10 UI

API Integration

REST API

JavaScript API

Authentication

Login

Params

Response

Customer Authentication

REST API

JavaScript API

Merchant Authentication

REST API

JavaScript API

Public Functions

getProducts - Retrieving of Product and Plan Data

Call API Token of external Payment Service Providers

Customer Registration

Request Plan Data

Params

Response

Verification of Coupon Code

Params

Register

Parameters

Response

Confirmation after Registration

Params

Response

Subscription Management

List Customer Subscriptions

Params

Response

status

Call Customer and Plan data

Params

Response

Edit a Subscription

Params

Response

transition_type

Call of Account, Subscription and Plan Data

Params

Response

Updating a Subscription

Changes that take effect immediately

Changes that take effect when the next term starts

Params

Upgrading/Downgrading a Subscription

Params

Validations

Confirmation after Upgrade/Downgrade

Params

Response

Adding a new Subscription

Params

Validation

Confirmation after Subscription

Params

Response

Modify Subscription

cancelSubscription - Cancel a Subscription

Params

uncancelSubscription - Uncancel a Subscription

Params

Account functions

Get Customer Account Data

Params

Response

Updating the Customer’s Account Data

Params

Validation

Updating the Customer’s Password

Params

Validation

Request body for REST integration: `cc_betterpayment`

Response: `cc_betterpayment`

Request body for REST integration: `cc_micropayment`

Response: `cc_micropayment`