API Authentication

API authentication is handled with HTTP Basic access authentication.(email:token)

If you are not using HTTP basic-auth, you can authenticate using input parameters

Input Parameters
Parameter Description
email The email you use to login to Putler
token API key generated from Putler

Obtaining your API Key

Create a new account in Putler of type “Putler Inbound API”. You will get a Key to use in all the API calls.

new-inbound-account

API Resource

Validate

Validate API Key and Email

URL
http://api.putler.com/inbound/

 

HTTP Method
HEAD

If you are not using HTTP HEAD, you can validate using action input parameters

 
Input Parameters
Parameter Value
action validate

 

Response
Status Code Description
200 Valid User
401 Unauthorised User

 

Store

Push transactions into Putler

URL
http://api.putler.com/inbound/

 

HTTP Method
POST

If you are not using HTTP POST, you can push transactions using action input parameters

 
Input Parameters
Parameter Value
action store

 

Request Header
Content-Type The MIME type of the request body.

  • application/json (Default)
  • text/csv
  • application/xml
NOTE:While sending transactions in CSV, CSV file should have header fields

 

Request
Field Required Description
Date Yes The date this order was created(MM/DD/YYYY)
Time Yes The time this order was created in GMT (HH:MM:SS AM/PM)
Type Yes
  • Main transaction – Shopping Cart Payment Received
  • Line item transaction – Shopping Cart Item
  • Buy now transaction- Web Accept Payment Received
  • Refund transaction- Refund
  • Subscription – Recurring Payment Received
Transaction_ID Yes Transaction ID of the order
Item_Title Yes
  • Main transaction – “Shopping Cart”
  • Line item/Buy now/Subscription transaction – The title of the product
Quantity Yes
  • Main transaction – Count of Line Items
  • Line item transaction – The quantity of the purchase for this product
Source Name of Payment gateway/ Shopping carts
Name Customer name
Status Status of the Order(Pending, Completed, Cancelled, Partially Refunded, Refunded)
Currency A 3-character currency code of the currency being used in this transaction (default is USD)
Gross Order total, including tax(default is 0.00)
Fee Total Fees paid for this transaction (default is 0.00)
Net Order total, inculding tax and excluding fees (default is 0.00)
From_Email_Address Contact email address
Item_ID Line item/Buy now/Subscription transaction -> The ID of the product
Shipping_and_Handling_Amount The value of shipping and handling cost (default is 0.00)
Insurance_Amount Total shipping insurance costs for this order (default is 0.00)
Discount Amount of discount for this transaction (default is 0.00)
Sales_Tax Total Tax paid for this transaction (default is 0.00)
Option_1_Name For Line item -> Product Option/Attribute -1 name
If there are more than 2 Option/Attribute, Send comma seperated list {Color:Red, Size:XL, Style:Simple}
Option_1_Value For Line item -> Product Option/Attribute -1 value
Option_2_Name For Line item -> Product Option/Attribute -2 name
Option_2_Value For Line item -> Product Option/Attribute -2 value
Reference_Txn_ID For Refund Transaction -> Transaction ID of parent Transaction
Invoice_Number Invoice or Tracking number
Balance Account balance if any (default is 0.00)
Note Any additional Order notes
Address_Line_1 Line 1 of street address
Address_Line_2 Line 2 of street address
Town_City Name of city
State_Province State/province name
Zip_Postal_Code Zip or postal code
Country Country full name
Contact_Phone_Number Contact phone number
Subscription_ID For Subscription transaction ->Subscription id

Specifics on Shopping cart payment

  • For more than 1 Line items
  • Seperate Transactions for each line items

 

Eg:  Order with 3 Line items, there will be 4 entries, viz. 1 entry for main order and 3 entries for each line items

Sample CSV with headers

"Date","Time","Source","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Shipping_and_Handling_Amount","Option_1_Name","Option_1_Value","Quantity","Note","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number"
"10/24/13",06:02:00 AM,"XYZ Gateway","Chirag B","Shopping Cart Payment Received","Completed","USD",409,0,409,"john@putler.com",46,"Shopping Cart",,10,,,3,"Order Note","Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",06:02:00 AM,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",149,,,"john@putler.com",46,"Product-1","P-45",0,"Color","Black",1,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",06:02:00 AM,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",150,,,"john@putler.com",46,"Product-2","P-37",0,"Color","Red",2,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135
"10/24/13",06:02:00 AM,"XYZ Gateway","Chirag B","Shopping Cart Item","Completed","USD",100,,,"john@putler.com",46,"Product-3","P-19",0,"Color","Yellow",1,,"Powai","Borivali","mumbai","MH",444554,"IN",95323135

Specifics on Buy Now payment

Each transaction will have only 1 entry.

Sample CSV with headers

"Date","Time","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Option_1_Name","Invoice_Number","Quantity","Balance","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number"
10/29/13,03:24:52 AM,"Chirag B","Web Accept Payment Received","Completed","USD",29,-1.14,27.86,"john@putler.com","5EA652410Y693721T","Product-1","MUTD","Color:red, Size: XL, Style:Simple","RT-9871",1,819.57,"Street1","Street2","City","CA",95101,"United States",98512154552

Specifics on Refund Transaction

New entry for Each refunds
Required feilds: Reference_Txn_ID

Sample CSV with headers

"Date"," Time"," Name"," Type"," Status"," Currency"," Gross"," Fee"," Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID"," Sales_Tax"," Reference_Txn_ID"," Quantity","Address_Line_1","Address_Line_2","Town_City","State_Province","Zip_Postal_Code"," Country"
10/29/13,03:05:29 AM,"Chirag B","Shopping Cart Payment Received","Partially Refunded","USD",50.5,-1.76,48.74,"john@putler.com","5X16702303884432U","Shopping Cart",,0.5,,1,"Street1","Street2","City","CA",95101,"United States"
10/29/13,03:05:29 AM,"Chirag B","Shopping Cart Item","Partially Refunded","USD",50,,,"john@putler.com","5X16702303884432U","Product-1","RM-7",,,1,"Street1","Street2","City","CA",95101,"United States"
10/29/13,04:05:38 AM,"Chirag B","Refund","Completed","USD",-20,0.58,-19.42,"john@putler.com","5L671541UP2927356",,,,"5X16702303884432U",,,,,,,

Specifics on Subscription Transaction

Each subscription transaction will have only 1 entry
Required feilds: Subscription_ID

"Date","Time","Name","Type","Status","Currency","Gross","Fee","Net","From_Email_Address","Transaction_ID","Item_Title","Item_ID","Balance","Address_Line_1","Town_City","State_Province","Zip_Postal_Code","Country","Contact_Phone_Number","Subscription_ID"
10/29/13,03:36:11 AM,"Chirag B","Recurring Payment Received","Completed","USD",2,-0.36,1.64,"john@putler.com","0G565730603123547","Weather Updates","MET-2013",821.21,"1Test address","San Jose","CA",95131,"United States",6543332132,"Sub-7562396"

Error Codes

Status Code Description
400 Authorization Failed
401 Unauthorised User
404 Unknown Action
500 Could not store transactions