Developer Documents

Introduction

APIs are HTTP-based APIs for authorization. API request and response bodies are formatted in JSON.

Authentication

When you click on Generate Keys button from the InsurePay Website API's section, you will get two keys that is Public Key and Private Key. Refresh Key can be generated via API.

Key Description
Public Public key will not change once it is generated in other words it's a Unique Key
Private Private Key can be generated as many times as you click on Generate Key button and of course once you change/ click on generate key button the previous generated key will not work
Refresh Required for making the payment. It is valid for only one time
Request & Response

To construct a REST API request, combine below components and return response in json format:

Attribute Description
HTTP Method POST
End Point https://zifflepay.com/v2/states
Header Required. Includes the Authorization header with the access identifier and token Accept Content-Type Access-Identifier Access-Token Refresh-Token
Request Data Optional. accept only JSON format {"country_code": "US"}
Response Data Return the JSON format with success/error code {"code":"200","message":"success","country": [{"State": {"id": "123","name": "Alaska","code": "AK"}}]}

Request

curl POST https://zifflepay.com/v2/states/

-H "Accept : application/json"

-H "Content-Type : application/json"

-H "Access-Identifier : Access-Identifier"

-H "Access-Token : Access-Token"

-d 

{"country_code":"US"}

Response

{
    "code": "200",
    "message": "success",
    "country": [
        {
            "State": {
                "id": "123",
                "name": "Alaska",
                "code": "AK"
            }
        }
    ]
}
End Point

A unique URL that represents an object or collection of objects

Type End-Point Description
Token
Refresh Token https://zifflepay.com/v2/tokens/refresh/ Generate Regresh Token
Client
Create https://zifflepay.com/v2/clients/create/ Create new client
Item
Create https://zifflepay.com/v2/items/create/ Create new item
Invoice
Send https://zifflepay.com/v2/invoices/send/ Create new invoice and send
Payment https://zifflepay.com/v2/invoices/payment/ Create new invoice and payment
Country
List https://zifflepay.com/v2/countries/ Get country list
State
List https://zifflepay.com/v2/states/ Get state list basis of country-code
Response Code

API calls return HTTP status codes. API calls also return JSON response bodies that include information. Each REST API request returns a success or error HTTP status code

Code Description
1 Success
2 Header missing
3 Body missing
4 Header invalid
5 Body invalid
Token
101 Token missing
102 Token invalid
Client
201 Client missing
202 Client invalid
Item
301 Item missing
302 Item invalid
Invoice
401 Invoice missing
402 Invoice invalid
Client

The Client's API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers. The client object define client's details, such as action, company_name , first_name, last_name, email, username, address, country_code, state_code, city, zip, phone_number, cell_phone and so on.

Create

Add new client.

POST
Request Data
action enum required
Maximum length : 20
Pre-defined keyword. Define the operation of client.

client_create create invoice.

company_name alphanumeric, special characters optional
Maximum length : 100
This is the Company Name for which client works.It will allow characters, numbers, special characters.
first_name string required
Maximum length : 30
This describes the first name of the person for whom the invoice is to be generated.
last_name string required
Maximum length : 30
This describes the last name of the person for whom the invoice is to be generated.
email string required
Maximum length : 50
This field will be required to sent an email with invoice/new client/ updated/ etc to the client.
username string optional
Maximum length : 15
This field will be used to enter the username of client.
address alphanumeric, special characters required
Maximum length : 120
Address of the client.
country_code string required
Maximum length : 5
Country codes are as shown in ISO 3166. Format: US.
Please find the accepted country code
state_code string required
Maximum length : 5
State codes are as shown in ISO 3166. Format: NY
Please find the accepted state code
city string required
Maximum length : 20
Client's city name
zip alphanumeric required
Maximum length : 8
Client's zip-code
phone_number number optional
Maximum length : 10
Client's phone number.
cell_phone number optional
Maximum length : 10
Client's cell phone.
send_notification boolean optional
Default : false
If true send email notification on client email with login credentials (username, password, login_url).
Response Data
code number
A successful request return the 1 status code otherwise return error code.
Please find the list of possible response code
message string
Return textual response.
client object
If request is completed successfully then response contain client object. The client object define client's details, such as first name, last name, email, username, password, login url and so on.
Client object definition

Request

curl POST https://zifflepay.com/v2/clients/create/

-H "Accept : application/json"

-H "Content-Type : application/json"

-H "Access-Identifier : Access-Identifier"

-H "Access-Token : Access-Token"

-d 

{
    "action": "client_create",
    "company_name": "Superior Insurance",
    "first_name": "Derick ",
    "last_name": "Pegram",
    "email": "derick.pegram@superiorInsurance.com",
    "username": "derick123",
    "address": "12000 Washington Street Suite 290",
    "country_code": "US",
    "state_code": "CO",
    "city": "Denver",
    "zip": "80022",
    "phone_number": "8574558555",
    "cell_phone": "8456985225",
    "send_notification": false
}

Response

{
    "code": 200,
    "message": "success",
    "client": {
        "company_name": "Superior Insurance",
        "first_name": "Derick ",
        "last_name": "Pegram",
        "email": "derick.pegram@superiorInsurance.com",
        "username": "derick123",
        "password": "THZXEFO@SW",
        "login_url": "https://zifflepay.com/users/login/",
        "address": "12000 Washington Street Suite 290",
        "country_code": "US",
        "state_code": "CO",
        "city": "Denver",
        "zip": "80022",
        "phone_number": "8574558555",
        "cell_phone": "8456985225"
    }
}
Item

The Item's API allows you to create, delete, and update item. An array of item object. The item object define item's details, such as action, name, description, unit_cost, quantity, tax1, tax2, service_type and unit_in_stock.

Create

Add new item.

POST
Request Data
action enum required
Maximum length : 20
Pre-defined keyword. Define the operation of item.

item_create create item.

name string required
Maximum length : 80
This is the name of the item. It will allow only characters.
description alphanumeric, special characters required
Maximum length : 120
This describes the item, description can be the explanation of the item.
unit_cost decimal required
Maximum length : 10
Format : 123.00
Unit cost of per item.
tax1 decimal optional
Maximum length : 5
Format : 12.25
Default : 0.00
Tax1 of item if provided. Condisidering in percent.
tax2 decimal optional
Maximum length : 5
Format : 13.75
Default : 0.00
Tax2 of item if provided. Condisidering in percent.
service_type boolean optional
Default : false
If value is true then item will be considered as service type.
unit_in_stock number optional
Maximum length : 10
Format : 12345
Default : 0/1
It shows the stock of item. If item is not service type then value will be 0 (zero) otherwise 1 by default in case value defines during item creation.
Response Data
code number
A successful request return the 1 status code otherwise return error code.
Please find the list of possible response code
message string
Return textual response.
item object
If request is completed successfully then response contain item object. The item object define item's details, such as name, description, unit cost and so on.
Item object definition

Request

curl POST https://zifflepay.com/v2/items/create/

-H "Accept : application/json"

-H "Content-Type : application/json"

-H "Access-Identifier : Access-Identifier"

-H "Access-Token : Access-Token"

-d 

{
    "action": "item_create",
    "name": "Health Insurance",
    "description": "Long terms. 35 years plan.",
    "unit_cost": "100",
    "tax1": "2.00",
    "tax2": "3.00",
    "service_type": true,
    "unit_in_stock": "0"
}

Response

{
    "code": 200,
    "message": "success",
    "item": {
        "name": "Health Insurance",
        "description": "Long terms. 35 years plan.",
        "unit_cost": "100",
        "tax1": "2.00",
        "tax2": "3.00",
        "service_type": true,
        "unit_in_stock": "0"
    }
}
Invoice

Use the Invoice API to create, send, and manage invoices. To manage invoices, you can also list invoices, show details for invoices, delete draft invoices, and cancel sent invoices. The invoice object include invoice's details such as client's details, item's details, amount's details and so on.

Send

Creates a invoice and sent to client

POST
Request Data
action enum required
Maximum length : 20
Define the method of invoice.

invoice_create Create new invoice.

invoice_action enum required
Maximum length : 20
Define the operation of invoice.

send Only send invoice notification to client after creation/updation.

payment Payment operation perform after invoice creation/updation.

type enum required
Maximum length : 20
Define the operation of invoice.

simple create simple invoice. Charge only one time.

recurring Create recurring invoice. Charge subscription basis.

date_of_issue string required
Maximum length : 8
The date of issuing the invoice.
po_number number optional
Maximum length : 10
Format : 12345, 67890
Define the PO number as a reference.
discount decimal optional
Maximum length : 5
Format : 7.50
Define the discount if applicable. Condisidering in percent.
send_notification boolean optional
Default : false
If true then send invoice detail via email and/or sms to client.
send_invoice_pdf boolean optional
Default : false
If true then send pdf file of invoice with invoice detail via email to client. send_notification must be true if send_invoice_pdf is set as true
inform_via boolean optional
Default : Email
Define the communication chanel for how to inform client about invoice. send_notification must be true if inform_via is defined.
client object required
The client object define client's details, such as action, company_name , first_name, last_name, email, username, address, country_code, state_code, city, zip, phone_number, cell_phone and so on.
Client object definition
items array required
An array of item object. The item object define item's details, such as action, name, description, unit_cost, quantity, tax1, tax2, service_type and unit_in_stock.
Item object definition
terms alphanumeric, special characters required
Maximum length : 120
Default : null
The conditions under which a agent will generate a invoice
notes alphanumeric, special characters optional
Maximum length : 120
Default : null
Short description or notes as a remark.
Response Data
code number
A successful request return the 1 status code otherwise return error code.
Please find the list of possible response code
message string
Return textual response.
invoice object
If request is completed successfully then response contain invoice object. The invoice object define invoice's details such as client's details, item's details, amount's details and so on.
Client object definition

Request

curl POST https://zifflepay.com/v2/invoices/send/

-H "Accept : application/json"

-H "Content-Type : application/json"

-H "Access-Identifier : Access-Identifier"

-H "Access-Token : Access-Token"

-d 

{
    "action": "invoice_create",
    "invoice_action": "send",
    "type": "simple",
    "po_number": "123456",
    "date_of_issue": "2018-08-25",
    "discount": "0.00",
    "send_notification": "False",
    "send_invoice_pdf": "False",
    "inform_via": "Email",
    "terms": "",
    "notes": "",
    "client": {
        "action": "client_create",
        "company_name": "Superior Insurance",
        "first_name": "Derick ",
        "last_name": "Pegram",
        "email": "derick.pegram@superiorInsurance.com",
        "username": "derick123",
        "address": "12000 Washington Street Suite 290",
        "country_code": "US",
        "state_code": "CO",
        "city": "Denver",
        "zip": "80022",
        "phone_number": "8574558555",
        "cell_phone": "8456985225",
        "send_notification": false
    },
    "items": [
        {
            "action": "item_create",
            "name": "Health Insurance",
            "description": "Long terms. 35 years plan.",
            "unit_cost": "10",
            "quantity": "1",
            "tax1": "2.00",
            "tax2": "3.00",
            "service_type": true,
            "unit_in_stock": "0"
        }
    ]
}

Response

{
    "code": 1,
    "message": "success",
    "invoice": {
        "id": "1998",
        "invoice_no": "000006",
        "action": "invoice_create",
        "invoice_action": "send",
        "type": "simple",
        "po_number": "123456",
        "discount": "0.00",
        "send_notification": true,
        "send_invoice_pdf": true,
        "send_invoice_reminder": false,
        "inform_via": "Email",
        "invoice_status": "sent",
        "terms": "",
        "notes": "",
        "client": {
            "company_name": "Superior Insurance",
            "first_name": "Derick ",
            "last_name": "Pegram",
            "email": "derick.pegram@superiorInsurance.com",
            "username": "derick123",
            "password": "THZXEFO@SW",
            "login_url": "https://zifflepay.com/users/login/",
            "address": "12000 Washington Street Suite 290",
            "country_code": "US",
            "state_code": "CO",
            "city": "Denver",
            "zip": "80022",
            "phone_number": "8574558555",
            "cell_phone": "8456985225",
            "send_notification": false
        },
        "items": [
            {
                "name": "Health Insurance",
                "description": "Long terms. 35 years plan.",
                "unit_cost": "10",
                "quantity": "1",
                "tax1": "2.00",
                "tax2": "3.00",
                "service_type": true,
                "unit_in_stock": "0"
            }
        ],
        "amount": {
            "total": "10.00",
            "tax": "0.00",
            "discount": "0.00",
            "processing_fees": "5.00",
            "paid": "0.00",
            "balance": "15.00"
        }
    }
}
Object Definition

The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources

Client

The client details, such as first name, last name, email, username, password, login url and so on.

company_name alphanumeric, special characters
This is the Company Name for which client works.
first_name string
This describes the first name of the person for whom the invoice is to be generated.
last_name string
This describes the last name of the person for whom the invoice is to be generated.
email string
This field will be required to sent an email with invoice/new client/ updated/ etc to the client.
username alphanumeric
If not provided while client creating time then username generated by system.
password alphanumeric, special characters
Password generated by system.
login_url url
Login url into insurepay.
address alphanumeric, special characters
Address of the client.
country_code string
Country codes are as shown in ISO 3166. Format: US.
state_code string
State codes are as shown in ISO 3166. Format: NY
city string
Client's city name
zip alphanumeric
Client's zip-code
phone_number number
Client's phone number.
cell_phone number
Client's cell phone. 
{
    "company_name": "Superior Insurance",
    "first_name": "Derick ",
    "last_name": "Pegram",
    "email": "derick.pegram@superiorInsurance.com",
    "username": "derick123",
    "password": "THZXEFO@SW",
    "login_url": "https://zifflepay.com/users/login/",
    "address": "12000 Washington Street Suite 290",
    "country_code": "US",
    "state_code": "CO",
    "city": "Denver",
    "zip": "80022",
    "phone_number": "8574558555",
    "cell_phone": "8456985225"
}
Item

The item details, such as name, description, unit cost and so on.

name string
This is the name of the item.
description alphanumeric
This describes the item, description can be the explanation of the item.
unit_cost decimal
This field will be used to enter the unit cost of per item.
quantity number
It will with invoice response. It shows quantity of item in invoice.
tax1 decimal
Tax1 of item if provided. Condisidering in percent.
tax2 decimal
Tax2 of item if provided. Condisidering in percent.
service_type boolean
If value is true then item will be considered as service type.
unit_in_stock number
It shows the stock of item. If item is not service type then value will be 0 (zero) otherwise 1 by default in case value defines during item creation. 
{
    "name": "Health Insurance",
    "description": "Long terms. 35 years plan.",
    "unit_cost": "100",
    "quantity": "1",
    "tax1": "2.00",
    "tax2": "3.00",
    "service_type": true,
    "unit_in_stock": "0"
}

© 2018 R2P2 Inc. ZifflePay