API Documentation

zferral API


Introduction

Authentication of affiliates

API Objects

Payout

Methods:

Examples:


All of the payout attribute fields are returned from GET (read) operations. Only those attributes not marked as read only may be set via POST (create) operations. Only those attributes marked as edit may be set via PUT (update) operations.

Parameters:

  • id INT (Read Only) The unique identifier for this payout
  • affiliate_id INT (Required) Affiliate id
  • payout_status_id INT (Edit) Payout status
  • amount DECIMAL(10,2) (Required) Amount of payout
  • created_at TIMESTAMP (Read Only) The creation date for this payout
  • Payout statuses: (pending, approved, completed, canceled)


Methods

create - creates new payout

URL: "https://<subdomain/>.zferral.com/api/<api_key>/payout.<format>"
Method: POST
Format: xml or json
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The created payout id
XML and JSON example


update - edits or updates data of payout object

URL: "https://<subdomain>.zferral.com/api/<api_key>/payout/<id>.<format>"
Method: PUT
Format: xml or json
Required Parameters: id and XML or JSON data, as specified by the required attributes
Response: The updated payout id
XML and JSON example


get – retrieves data of payout object

URL: "https://<subdomain>.zferral.com/api/<api_key>/payout/<id>.<format>"
Method: GET
Format: xml or json
Required Parameters: id
Response: An single payout
XML and JSON example


list – lists payouts

URL: "https://<subdomain>.zferral.com/api/<api_key>/payouts.<format>"
Method: GET
Format: xml or json
Optional Parameters: affiliate_id, page, limit
Response: An array of Payouts, up to 50 per page
XML and JSON example

create - Usage Example

Scenarios [examples]:

Requirements:

  • Correct <api_key>
  • Returned data format <format>


  1. Scenario: Creating payout

    Request

    a) XML 

          <?xml version="1.0" encoding="UTF-8" ?>
      <payout>
        <affiliate_id>1</affiliate_id>
        <amount>350</amount>
      </payout>

    b) JSON 

            {
          "payout" : {
            "affiliate_id"  : "2",
            "amount"        : "500"
        }}


    Response (return status code "201 Created"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payout>
          <id>43</id>
        </payout>

    b) JSON 

            {
         "commission" : {
            "id" : "59",
        }}

  2. Scenario: Creating Payout (sending not all required parameters)

    Request

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payout>
          <affiliate_id>1</affiliate_id>
        </payout>

    b) JSON 

            {
         "payout" : {
            "affiliate_id"  : 1,
        }}


    Response (return status code "422 Unprocessable Entity"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <errors>
            <amount>Required.</amount>
        </errors>

    b) JSON 

            {
         "errors": {
            "amount":"Required.",
        }}


update - Usage Example

Requirements:

  • Correct <api_key>
  • Returned data format <format>
  • Correct <id>


  1. Scenario: Update payout (sending correct parameter : payout_status_id)

    Request

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payout>
          <payout_status_id>approved</payout_status_id>
        </payout>

    b) JSON 

            {
         "payout" : {
            "payout_status_id" : approved
        }}


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payout>
          <id>57</id>
        </payout>

    b) JSON 

            {
         "payout" : {
            "id" : "57",
        }}


get – Usage Example

Scenarios [examlpes]:

Requirements:

  • Correct <api_key>
  • Returned data format <format>
  • Correct <id>


  1. Scenario: Get payout data


    Request

    URL: "https://<subdomain>.zferral.com/api/<api_key>/payout/39.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payout>
            <id>61</id>
            <affiliate_id>23</affiliate_id>
            <payout_status_id>pending</payout_status_id>
            <amount>450.00</amount>
            <created_at>2010-05-25 09:22:14</created_at>
        </payout>

    b) JSON 

            {
          "payout": {
            "id"              : 61,
            "affiliate_id"    : 23,
            "payout_status_id": pending,
            "amount"          : "450.00",
            "created_at"      : "2010-03-25 09:22:14",
        }}


list – Usage Example

Scenarios [examples]:

Requirements:

  • Correct <api_key>
  • Returned data format <format>


  1. Scenario: Get list of payouts


    Request

    URL: "https://<subdomain>.zferral.com/api/<api_key>/payouts.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <payouts type="array">
            <payout>
                <id>61</id>
                <affiliate_id>23</affiliate_id>
                <payout_status_id>pending</payout_status_id>
                <amount>250.00</amount>
                <created_at>2010-05-25 09:22:14</created_at>
            </payout>
            <payout>
                <id>62</id>
                <affiliate_id>13</affiliate_id>
                <payout_status_id>completed</payout_status_id>
                <amount>450.00</amount>
                <created_at>2010-05-25 09:22:14</created_at>
            </payout>
            <payout>
                <id>63</id>
                <affiliate_id>3</affiliate_id>
                <payout_status_id>pending</payout_status_id>
                <amount>450.00</amount>
                <created_at>2010-05-25 09:22:14</created_at>
            </payout>
            <payout>
               <id>64</id>
                <affiliate_id>24</affiliate_id>
                <payout_status_id>completed</payout_status_id>
                <amount>350.00</amount>
                <created_at>2010-06-25 09:22:14</created_at>
            </payout>
            <payout>
                <id>65</id>
                <affiliate_id>23</affiliate_id>
                <payout_status_id>canceled</payout_status_id>
                <amount>450.00</amount>
                <created_at>2010-06-26 09:22:14</created_at>
            </payout>
        </payouts>

    b) JSON 

            {
         "payouts" : {
            "payout" : {
              (...)
            },
            "payout" : {
              (...)
            },
            "payout" : {
              (...)
            }
        }}