NAV

Introduction

SimplePin's authorization framework enables third-party applications to obtain access to important resources like customers and invoices. Before you get started with making API requests, you have to create a company account. Once an account is registered you will obtain your authorization and token, which will be used to identify your company when calling the SimplePin API. It's also possible to create a company account using the SimplePin API. In order to do so, you need to be a trusted partner.

SimplePin API entities

API controllers and their calls allow you to perform manipulations on the following data/business entities:

Entity
Description
Partner
A Partner in the SimplePin platform represents a trusted legal entity which could create multiple company entries using SimplePin's API. If you are a developer and would like to become a partner, you should start with the certification process by submitting a request in the CONTACT US form.
Company
A Company represents a business which intends to transact with its customers. A better example could be an insurance brokerage, accounting or law firm.
User
A user represents a company's employee with specific permissions. There are 4 types of users: company owner (could be only one), manager, customer care and accounting. Every type of user has a separate set of permissions.
Customer
A ccustomer in the SimplePin platform belongs to a company. SimplePin requires you to have a customer entity in order to obtain payment. All historical modifications of the customer entity are stored in a database to keep track of all changes.
Invoice
An invoice in SimplePin's platform belongs to a customer. All historical modifications of an invoice's entity are stored in a database to keep track of changes. There are different invoice statuses: DRAFT, SENT, CANCELLED, PAID. An invoice can be reopened and once the invoice is PAID by the customer, the user can't reopen the invoice.
Transaction
A transaction belongs to the Invoice. There are 4 statuses available for a transaction: SUCCESS, PENDING, FAILED and ERROR.
Deposit
A deposit in SimplePin's platform represents a unique withdrawal entry which accumulates all the transactions collected during the payment of invoices.

Staging vs Production environment

In order to achieve the highest quality of integration, developers should start by integrating SimplePin's STAGING environment first. Only after the integration is completed and certified by SimplePin's integration team, the PRODUCTION environment should be configured.

Credentials to access your SimplePin company account

To start the integration process, create a company account in the staging environment with the following link:

https://staging.simplepin.com/company/sign-up-step1

Follow all registration steps and activate your account by validating your email address.

Configuring Authorization Token keys for API integration

Every API call is identified by secure parameters in headers: Authorization and Token. To configure these parameters, login into SimplePin's admin interface at https://staging.simplepin.com/company/sign-in and go to settings / API where you will be presented with a configuration interface.

SimplePin allows developers to create multiple sets of keys to identify different clients.

Webhook notifications

If you would like to receive status update notifications on different events (payment status, customer update, invoice update etc..) you can configure one or multiple URLs in settings / API. 

End-point URL for API calls

As soon as an environment is configured, you can use the following URL to interact with SimplePin's API: https://staging.simplepin.com/api/v2

Integration steps

Now that everything is ready for you to start integration, follow these integration steps:

1. In an ERP or any business management make sure that the customer and the invoice information is ready.

2. With methods getCustomer, updateCustomer, addCustomer make sure that the information exists in SimplePin's database.

3. With Customer's Policy_ID create a new invoice using the addInvoice method.