Zippy

Documentation on zippy and reference implementation.

Note that in the following examples {*uuid} refers to an actual uuid.

Sellers

POST /provider/reference/sellers/

Create a seller.

Request

Parameters:
  • uuid – uuid of the seller.
  • email – email of the seller.
  • name – name of the seller.
  • status – status of the seller.
  • seller – the url to the seller as returned from seller creation.

Example:

{
    "seller": "{seller-url}",
    "email": "jdoe@example.org",
    "name": "John",
    "status": "ACTIVE",
    "uuid": "{seller-uuid}"
}

Response

Status Codes:
  • 201 Created – seller created. Examine the response contents to see the status of the seller and a pointer to the new seller.
  • 400 Bad Request – there was a problem with the seller creation. Examine the response contents for more information.

See retrieving a seller for detail on the response.

GET /provider/reference/sellers/{seller-uuid}/

Retrieve a seller.

Response

Status Codes:
  • 200 OK – seller retrieved. Examine the response contents to see the status of the seller and a pointer to the seller.
  • 400 Bad Request – there was a problem with the seller retrieval. Examine the response contents for more information.
Parameters:
  • email – email of the seller.
  • name – name of the seller.
  • status – status of the seller.
  • agreement – an optional date that can be used for terms validation.
  • resource_name – the name of the resource.
  • id – the primary key of the resource.
  • resource_uri – the URI of the resource.
  • uuid – a UUID for the resource.
  • seller – the URI of the generic seller.

Example successful seller retrieval:

{
    "agreement": "",
    "email": "jdoe@example.org",
    "name": "John",
    "resource_name": "sellers",
    "id": "{seller-id}",
    "resource_uri": "/provider/reference/sellers/{seller-id}",
    "status": "ACTIVE",
    "seller" "/generic/seller/1/",
    "uuid": "{seller-uuid}"
}
PUT /provider/reference/sellers/{seller-uuid}/

Update a seller.

Request

All parameters are optionals.

Parameters:
  • uuid – uuid of the seller.
  • email – email of the seller.
  • name – name of the seller.
  • status – status of the seller.

Example:

{
    "name": "Jack"
}

Response

Status Codes:
  • 201 Created – seller created. Examine the response contents to see the status of the seller and a pointer to the seller.
  • 400 Bad Request – there was a problem with the seller modification. Examine the response contents for more information.
Parameters:
  • email – email of the seller.
  • reference – the contents of the response from the reference server.
  • > name (reference) – name of the seller.
  • > status (reference) – status of the seller.
  • > agreement (reference) – an optional date that can be used for terms validation.
  • > resource_name (reference) – the name of the resource.
  • > id (reference) – the primary key of the resource.
  • resource_uri – the URI of the resource.

Example successful seller modification:

{
    "id": "{seller-uuid}",
    "reference": {
        "agreement": "",
        "email": "jdoe@example.org",
        "name": "Jack",
        "resource_name": "sellers",
        "resource_uri": "{seller-uri}",
        "id": "{seller-uuid}",
        "status": "ACTIVE"
    },
    "resource_uri": "/sellers/{seller-uuid}",
    "seller": "{seller-uri}"
}

Products

Using that newly created “seller”, we can now create a “product”.

POST /provider/reference/products/

Create a product.

Request

Parameters:
  • name – name of the product.
  • seller_product – url of the generic product.
  • seller_reference – url of the reference seller.
  • uuid – a uuid for this product.

Example:

{
    "name": "Product name",
    "uuid": "{product-uuid}",
    "seller_product": "{seller-product-url}",
    "seller_reference": "{seller-reference-url}"
}

Response

Status Codes:
  • 201 Created – product created. Examine the response contents to see the status of the product and a pointer to the new product.
  • 400 Bad Request – there was a problem with the product creation. Examine the response contents for more information.
Parameters:
  • id – the primary key of the resource.
  • seller_product – URI of the generic product.
  • seller_reference – URI of the reference seller.
  • reference – the contents of the response from the reference server.
  • > external_id (reference) – the external id.
  • > name (reference) – name of the product.
  • > resource_name (reference) – the name of the resource.
  • > resource_uri (reference) – the URI of the resource.
  • > seller_id (reference) – uuid of the seller.
  • > status (reference) – status of the product.
  • > uuid (reference) – the uuid of the product.

Example successful product creation:

{
    "id": "{product-id}",
    "reference": {
        "external_id": "{external-uuid}"
        "name": "Product name",
        "resource_name": "products",
        "resource_uri": "/products/reference/{product-id}",
        "seller_id": "{seller-uuid}",
        "status": "ACTIVE",
        "uuid": "{product-uuid}"
    },
    "resource_uri": "/products/reference/{product-id}",
    "seller_product": "{seller-product-url}",
    "seller_reference": "{seller-reference-url}",
}

Transactions

Let’s buy that product by creating a “transaction”.

POST /provider/reference/transactions/

Create a transaction.

Request

Parameters:
  • carrier – the carrier of the transaction.
  • currency – the currency of the transaction.
  • price – the price of the transaction.
  • product_id – uuid of the product.
  • ext_transaction_id – uuid of the transaction.
  • pay_method – the payment method of the transaction.
  • region – the region concerned by the transaction.
  • error_url – the URL to reach in case of error of the transaction.
  • success_url – the URL to reach in case of success of the transaction.

Example:

{
    "carrier": "USA_TMOBILE",
    "currency": "EUR",
    "price": "0.99",
    "product_id": "{product-uuid}",
    "error_url": "http://marketplace.firefox.com/mozpay/provider/error/",
    "success_url": "http://marketplace.firefox.com/mozpay/provider/success/",
    "ext_transaction_id": "{transaction-uuid}",
    "pay_method": "OPERATOR",
    "region": "123"
}

Response

Status Codes:
  • 201 Created – transaction created. Examine the response contents to see the status of the transaction and the token.
  • 400 Bad Request – there was a problem with the transaction creation. Examine the response contents for more information.
Parameters:
  • carrier – the carrier of the transaction.
  • currency – the currency of the transaction.
  • price – the price of the transaction.
  • product_id – uuid of the product.
  • ext_transaction_id – uuid of the transaction.
  • pay_method – the payment method of the transaction.
  • region – the region concerned by the transaction.
  • error_url – the URL to reach in case of error of the transaction.
  • success_url – the URL to reach in case of success of the transaction.
  • resource_name – the name of the resource.
  • id – the primary key of the resource.
  • resource_uri – the URI of the resource.
  • status – status of the transaction. Should be STARTED at this point.
  • token – the security token for the transaction.

Example successful transaction creation:

{
    "carrier": "USA_TMOBILE",
    "currency": "EUR",
    "product_id": "{product-uuid}",
    "error_url": "http://marketplace.firefox.com/mozpay/provider/error/",
    "success_url": "http://marketplace.firefox.com/mozpay/provider/success/",
    "ext_transaction_id": "{transaction-uuid}",
    "pay_method": "OPERATOR",
    "price": "0.99",
    "region": "123"
    "resource_name": "transactions",
    "id": "{product-uuid}",
    "resource_uri": "/transactions/{product-uuid}",
    "token": "97ccb8ced0318a2751e936e354848...",
    "status": "STARTED"
}

Terms Agreement

GET /provider/reference/sellers/{seller-uuid}/

Retrieve terms related to a given seller.

Response

Status Codes:
  • 200 OK – terms retrieved. Examine the response contents to see the content of the terms and an agreement date.
  • 400 Bad Request – there was a problem with the terms retrieval. Examine the response contents for more information.
Parameters:
  • terms – the text containing terms, can be lengthy.
  • agreement – the datetime of the agreement of the terms by the user.

Example successful terms retrieval:

{
    "terms": "Terms for seller: John...",
    "agreement": "2013-11-19T11:48:49.158Z"
}