Introduction

The Wizypay Affiliation API enables programmatic access to the Wizypay’s network of affiliate merchants and reward program.

The API is based on a HTTP/JSON webservice located at the following endpoint:

https://affiliation.api.wizypay.com

Resources

The API consists of four main types of resources:

  • Merchants
    A Merchant is an e-commerce store or service provider that is a member of Wizypay’s Affiliation Network. The merchant list, as for all other API resources, is updated in real-time.
  • Ads
    Ads are advertising media attached to merchants. Essentially, an ad is a banner or a text link, ready to be embedded on your side. Each ad has tracked links to grant you rewards when your users make purchases through our network.
  • Offers
    Offers are an extension to ads: they have a banner and a tracked link that advertise an offer/sale/special discount from a given merchant. Offers are often limited in time.
  • Categories
    Categories are the main classification for the API resources: merchants and ads.

The links provided through the Affiliation API are tracked: they generate, on click events, cookies stored on your users browsers. Those cookies are used to track purchases (or any other rewarded actions) made by your users on our Affiliation of merchants.

In case you need to partition your tracked links (and therefore your rewards) for different group of users, you can use sub-ids to customize the Wizypay tracked links. Adding a sub-id is simply appending a subid parameter to the tracked url query string. The value must be a positive 32 bits integer.

Example:

  • Original tracked link: http://go.wizypay.com/c/3255
  • Tracked link with your sub-id: http://go.wizypay.com/c/3255?subid=325

Categories

List

GET /categories

Returns the list of categories.

Note: The categories list is immutable for a given API version.

Example response

{
  "data": [
    { "id": 1, "name": "Mode" },
    { "id": 2, "name": "Beauté & Bien-être" },
    { "id": 3, "name": "Intérieur & Extérieur" },
    { "id": 4, "name": "Multimédia" },
    { "id": 5, "name": "Loisir, Voyage & Escapade" },
    { "id": 6, "name": "Sport" },
    { "id": 7, "name": "Bébé et Enfant" },
    { "id": 8, "name": "Culturels, Papeterie & Bureaux" },
    { "id": 9, "name": "Cadeaux & Gastronomie" }
  ]
}

Item

GET /categories/:id

Returns a category by id.

Example response

{
  "data": { "id": 1, "name": "Mode" }
}

Merchants

List

GET /merchants

Returns the list of merchants available for your account.

GET /categories/:category_id/merchants

Returns the list of your merchants filtered by the given category identifier.

GET /merchants?q=text

Returns the list of your merchants matching the full-text search query on the merchant name and description.

Example response:

{
  "data": [
    {
      "id": 189,
      "name": "Oxbow",
      "description": "Oxbow est la première marque de glisse (...)",
      "url": "http://www.oxbowshop.com/",
      "image_url": "http://i.imgur.com/Tc1oF0j.png",
      "primary_ad": {
        "data": {
          "id": 5457,
          "kind": "text",
          "text": "Oxbow",
          "ppc_url": "http://go.wizypay.com/c/3291",
          "ppv_url": "http://go.wizypay.com/v/3291",
          "html": "<img align=\"bottom\" width=\"1\" (...)>Oxbow</a>"
        },
        "meta": {
          "type":"ads"
        }
      },
      "categories":{
        "data": [ { "id": 6, "name":"Sport" }, { "id": 1, "name": "Mode" } ]
      }
    },
    /*...*/
  ],
  "meta": {
    "page": 2,
    "per_page": 200,
    "total_count": 256
  }
}

Item

GET /merchants/:id

Returns a merchant by id.

Example response

{
  "data": {
    "id": 189,
    "name": "Oxbow",
    "description": "Oxbow est la première marque de glisse (...)",
    "url": "http://www.oxbowshop.com/",
    "image_url": "http://i.imgur.com/Tc1oF0j.png",
    "primary_ad": {
      "data": {
        "id": 5457,
        "kind": "text",
        "text": "Oxbow",
        "ppc_url": "http://go.wizypay.com/c/3291",
        "ppv_url": "http://go.wizypay.com/v/3291",
        "html": "<img align=\"bottom\" width=\"1\" (...)>Oxbow</a>"
      },
      "meta": {
        "type":"ads"
      }
    },
    "categories":{
      "data": [ { "id": 6, "name":"Sport" }, { "id": 1, "name": "Mode" } ]
    }
  }
}

Ads

Ads have two tracked links: a click link: ppc_url, and a tracked image link: ppv_url. The image link leads to the banner resource in the case of image ads (kind = image). In the case of of text ads, the image link is a 1 pixel gif image used for ad display tracking.

List

GET /ads

Returns all the ads available for your account.

GET /ads?kind={text|image}

Returns ads filtered by their kind: image or text.

GET /merchants/:merchant_id/ads

Returns ads by merchant.

GET /categories/:category_id/ads

Returns ads by category.

Example response

{
  "data": [
    {
      "id": 5457,
      "kind": "text",
      "text": "Oxbow",
      "ppc_url": "http://go.wizypay.com/c/3291",
      "ppv_url": "http://go.wizypay.com/v/3291",
      "html": "<img align=\"bottom\" width=\"1\" (...)>Oxbow</a>",
      "merchant": {
        "data": { "id": 189, "name": "Oxbow" }
      }
    },
    {
      "id": 5458,
      "kind": "image",
      "width": 120,
      "height": 90,
      "ppc_url": "http://go.wizypay.com/c/3255",
      "ppv_url": "http://go.wizypay.com/v/3255",
      "html": "<a target=\"_blank\" href=\"http:/ (...)></a>",
      "merchant": {
        "data": { "id": 189, "name": "Oxbow" }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 500,
    "total_count": 37
  }
}

Item

GET /ads/:id

Returns an ad by id.

Example response

{
  "data": {
    "id": 5458,
    "kind": "image",
    "width": 120,
    "height": 90,
    "ppc_url": "http://go.wizypay.com/c/3255",
    "ppv_url": "http://go.wizypay.com/v/3255",
    "html": "<a target=\"_blank\" href=\"http:/ (...)></a>",
    "merchant": {
      "data": { "id": 189, "name": "Oxbow" }
    }
  }
}

Offers

List

GET /offers

Returns all the offers available for your account.

GET /categories/:category_id/offers

Returns offers filtered by matching the given category identifier.

Example response

{
  "data": [
    {
      "id": 10,
      "name": "Soldes hiver 2015",
      "description": "Equippez vous à petit prix pour les sports d'hiver",
      "start_date": "2015-01-09T00:00:00.000Z",
      "end_date": "2015-04-18T00:00:00.000Z",
      "badge": "-60%",
      "code": "C40001",
      "ppc_url": "http://go.wizypay.com/c/45103",
      "ppv_url": "http://go.wizypay.com/v/45103",
      "merchant": {
        "data": { "id": 189, "name": "Oxbow" }
      },
      "categories": {
        "data": [
          { "id": 1, "name": "Mode" }
        ]
      }
    },
    /*...*/
  ],
  "meta": {
    "page": 1,
    "per_page": 100,
    "total_count": 6
  }
}

Item

GET /offers/:id

Returns an offer by id.

Example response

{
  "data": {
    "id": 10,
    "name": "Soldes hiver 2015",
    "description": "Equippez vous à petit prix pour les sports d'hiver",
    "start_date": "2015-01-09T00:00:00.000Z",
    "end_date": "2015-04-18T00:00:00.000Z",
    "badge": "-60%",
    "code": "C40001",
    "ppc_url": "http://go.wizypay.com/c/45103",
    "ppv_url": "http://go.wizypay.com/v/45103",
    "merchant": {
      "data": { "id": 189, "name": "Oxbow" }
    },
    "categories": {
      "data": [
        { "id": 1, "name": "Mode" }
      ]
    }
  }
}

Errors

Access to a non-existing resource will amount to a 404 Not Found HTTP response code.

Access to a non authorized resources will amount to a 404 Not Found HTTP response code (no distinction is made between access to non-existing and not authorized resource).

Access to the api without prior authentication will amount to 401 Unauthorized.

Resources and Paging

In Wizypay APIs, the returned json has two top-level fields:

  • data: Mandatory field that points to the actual data being requested, be it an array of resources or a single resource.
  • meta: Optional field containing additional information about the returned data. It contains for instance paging information for collections or type information when it is not obvious from the context.

For resource collections, the paging information in the meta object indicates the current page, the page size and the total elements count with, respectively, page, per_page and total_count.

Example: Here is a example response for a request for a collection of resources Assuming the API endpoint being requested returns list of resources, the response is a json object having the following structure:

{
  "data": [ {...}, {...}, ... ],
  "meta": {
    "page": 1,
    "per_age": 25,
    "total": 4704
  }
}

Authentication

Wizypay APIs are secured by default. An API key and secret are mandatory to get access and interact with our APIs. If you don’t already have an API key/secret pair (or if you have lost them) you can request new credentials.

Access to Wizypay APIs are secured with the Hashed Message Authentication Mode with SHA-256 as underlying hashing function (a.k.a. HMAC-SHA256 see RFC 4846 and the wikipeda entry).

Required HTTP headers

Each request to the API endpoint needs the following HTTP headers to be set in order to be authenticated by the API server:

  • An Authorization header containing the API key concatenated to the authentication code computed from the request data combined with your API secret using the HMAC-SHA256 function. The Authorization header should have the following format:
    Authorization: WIZYPAY {Your Api Key}:{HMAC Authentication Code}
    Example with an API key of 1789:
    Authorization: WIZYPAY 1789:y3iZqjnAjw8D0Y2S5lzT+yAc0Y2S5ZqjnAlzrqk=
  • A Date header. The date should be within 15 minutes from the current time.
  • A Content-Type header, e.g.: text/html or application/x-www-form-urlencoded.

Computing the HMAC Authentication Code

The authentication code is derived from the following data:

  • http_verb is upper case string of the http method of the request. e.g.: GET, POST, PUT etc.
  • content_md5 is the request body MD5 digest computed as described in the Content-MD5 header specification (please notice that the digest value is needed for the computation but the HTTP header can be omitted).
  • content_type is the request content type as set in the required HTTP header Content-Type above.
  • resource_path is the request URL path, query string and anchor part. e.g.: The URL: https://example.com/users/324?name=Joe&age=55#profile has the a resource_path: /users/324?name=Joe&age=55#profile
  • date is the request date as set in the required HTTP header Date above.
  • your_api_secret your private API secret.
string_to_sign = http_verb     + "\n" +
                 content_type  + "\n" +
                 content_md5   + "\n" +
                 resource_path + "\n" +
                 date

authentication_code = Base64(Hmac_Sha256(your_api_secret, UTF8_Encoding_Of(string_to_sign)))

authorization_http_header = "Authorization: WIZYPAY " + your_api_key + ":" + authentication_code

A reference implementation is available on github.