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
ParameterDescription
emailThe email you use to login to Putler
tokenAPI 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
ParameterValue
actionvalidate

 

Response
Status CodeDescription
200Valid User
401Unauthorised 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
ParameterValue
actionstore

 

Request Header
Content-TypeThe 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
FieldRequiredDescription
DateYesThe date this order was created(MM/DD/YYYY)
TimeYesThe time this order was created in GMT (HH:MM:SS AM/PM)
TypeYes
  • 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_IDYesTransaction ID of the order
Item_TitleYes
  • Main transaction – “Shopping Cart”
  • Line item/Buy now/Subscription transaction – The title of the product
QuantityYes
  • Main transaction – Count of Line Items
  • Line item transaction – The quantity of the purchase for this product
SourceName of Payment gateway/ Shopping carts
NameCustomer name
StatusStatus of the Order(Pending, Completed, Cancelled, Partially Refunded, Refunded)
CurrencyA 3-character currency code of the currency being used in this transaction (default is USD)
GrossOrder total, including tax(default is 0.00)
FeeTotal Fees paid for this transaction (default is 0.00)
NetOrder total, inculding tax and excluding fees (default is 0.00)
From_Email_AddressContact email address
Item_IDLine item/Buy now/Subscription transaction -> The ID of the product
Shipping_and_Handling_AmountThe value of shipping and handling cost (default is 0.00)
Insurance_AmountTotal shipping insurance costs for this order (default is 0.00)
DiscountAmount of discount for this transaction (default is 0.00)
Sales_TaxTotal Tax paid for this transaction (default is 0.00)
Option_1_NameFor 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_ValueFor Line item -> Product Option/Attribute -1 value
Option_2_NameFor Line item -> Product Option/Attribute -2 name
Option_2_ValueFor Line item -> Product Option/Attribute -2 value
Reference_Txn_IDFor Refund Transaction -> Transaction ID of parent Transaction
Invoice_NumberInvoice or Tracking number
BalanceAccount balance if any (default is 0.00)
NoteAny additional Order notes
Address_Line_1Line 1 of street address
Address_Line_2Line 2 of street address
Town_CityName of city
State_ProvinceState/province name
Zip_Postal_CodeZip or postal code
CountryCountry full name
Contact_Phone_NumberContact phone number
Subscription_IDFor 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 CodeDescription
400Authorization Failed
401Unauthorised User
404Unknown Action
500Could not store transactions