ProfitShare.ninja API

To use ProfitShare.ninja as a project owner you will only need to implement a single call called ReportTransaction and be able to recognize and store value of two query string parameters called "psn-coupon" and "psn-email" and their relationship.

Optionally, you may want to implement a second API call called GetUserEmail.

Finally, your system must allow the user to enter a discount coupon on the checkout page.

In detail

psn-coupon - is a query string parameter that you will receive when we redirect a customer to one of the project's target URLs that you defined for the project. You have to store the value of this parameter in the current user's session. If the user registers in your system you must permanently store the coupon value with that user.

It is up to you how you store the coupon value - whether directly in the "users" table or using a relationship - but you must call the ReportTransaction method on ProfitShare.ninja whenever an user for which you have a coupon makes any purchase on your website or in your application.

psn-email - is a query string parameter that you will receive when a customer confirms their email to register for discounts. Because the customer has to manually confirm their email by clicking a link in an email message sent to them by us you will usually receive a this query string parameter within a call that duplicates a call received previously at some point but containing the psn-email as an additional parameter. When you receive this call you are required to store this email permanently until that customer eventually registers with you, which may not necessarily be the same day. You must link the received email address to the received psn-coupon and when the user eventually registers in your system you must permanently store the coupon against that user. If the customer has already registered with the same email and has a registered coupon against the account you do not have to do anything more.

For example, if your landing page for your listed project is www.yourwebsite.com/landing_page we will call it like so:
http://www.yourwebsite.com/landing_page?psn-coupon=2DGS-E39K
or http://www.yourwebsite.com/landing_page?psn-coupon=2DGS-E39K&psn-email=name@customer.com.


ReportTransaction - is a POST method on https://profitshare.ninja/api/ that you are required to call whenever a referred customer makes a purchase within your project.

The request:
This method accepts a JSON object in the following format:

    {
        CustomerEmail: "",              
        ReferrerCoupon: "",             
        YourTransactionTypeCode: "",    
        YourTransactionId: "",          
        TransactionTotal: 0,            
        TransactionProfit: 0,           
        TransactionCurrencyCode: "",    
        CustomerCountryCodeOrId: "",   
        ProjectPrivateKey: ""           
    }
CustomerEmail - REQUIRED.
ReferrerCoupon - REQUIRED. The value of psn-coupon you store with the customer.
YourTransactionTypeCode - The transaction code as defined in your project definition on PSN.
YourTransactionId - If you want us to remember and list on invoices related transaction ID from your system.
TransactionTotal - REQUIRED. Must be the total amount of the customer's purchase.
TransactionProfit - REQUIRED. Must be the total amount of profit the transaction generated.*
TransactionCurrencyCode - REQUIRED. The two letter ISO code of the currency of the transaction.
CustomerCountryCodeOrId - REQUIRED. If you know the customer's country report the two letter ISO country code. Otherwise report her IP address.
ProjectPrivateKey - To verify that this call really comes from you. You can find your project private key on the "Project edit page".

The response:
We will reply with the following JSON object:

    {
        Result: "",             
        YourTransactionId: "",              
        OurTransactionId: "",    
        CustomerDiscountAmount: 0,          
        PromoterShareAmount: 0  
    }
Result - Contains a result code of the call:
ok - The transaction was processed and recorded successfully.
invalid_private_key - The supplied project private key is invalid.
invalid_project_id_or_private_key - The supplied project private key is invalid or does not match the project.
not_found_customer - The customer was not found.
this_was_a_test - IMPORTANT: This purchase was a test purchase. You are now required to refund the complete payment immediately.
invalid_promoter_id - The promoter does not promote this project.
not_found_promoters - There are no promoters promoting this project.
falied_to_save_promoter_link - The promoter transaction link faild to save.
YourTransactionId - This just echoes back the transaction Id you sent us in the request.
OurTransactionId - Gives you the ID of the recorded transaction in our system, should it be useful for you.
CustomerDiscountAmount - IMPORTANT: If bigger than 0 you are obliged to subtract this amount from the customers total price as this is an amount the promoter decided to share with the customer. The PromoterShareAmount total will be lower by exactly this amount.
PromoterShareAmount - Informs your system how much profit share from this transaction you owe to the promoter who brought you the customer. (This and the previous value added together should match the profit share percentage set by you for this transaction type and the just reported profit.)
TOC
psn-coupon query parameter
psn-email query parameter
ReportTransaction POST method