Developers

This covers registering setting up a seller (who is normally an app developer) and registering their products with the payment provider.

Unlike most other payment systems, the merchant of record is not Mozilla or the payment provider, but the app developer. Setting up the developers account allows the developer to become the merchant of record.

This is a key difference between this payment system and other payment systems and the implications must be understood by the payment providers.

Note

In the following examples {*uuid} refers to an actual uuid.

Sellers

This API allows you to get/create sellers who can offer products for sale.

This API demonstrates a very simple get and post API for creating a seller. Typically a payment provider will require more information about a seller that is shown here, since the payment provider will likely want more information pertinent to developer payouts.

GET /sellers

Response

You get a list of all sellers. For example:

[
  {
    "status": "ACTIVE",
    "name": "John",
    "email": "jdoe@example.org",
    "resource_pk": "{seller-uuid}",
    "resource_name": "sellers",
    "resource_uri": "/sellers/{seller-uuid}",
    "agreement": ""
  },
  ...
]
Status Codes:
  • 200 – success.
GET /sellers/:uuid

Response

You get a seller object matching :uuid. For example:

{
  "status": "ACTIVE",
  "name": "John",
  "email": "jdoe@example.org",
  "resource_pk": "{seller-uuid}",
  "resource_name": "sellers",
  "resource_uri": "/sellers/{seller-uuid}",
  "agreement": ""
}
Status Codes:
  • 200 – success.
POST /sellers

Request

Parameters:
  • uuid – A unique ID for the seller.
  • status

    A status for the seller. Possible values:

    ACTIVE
    Activated seller.
    INACTIVE
    Inactived seller.
    DISABLED
    Deactivated seller.
  • name – A name for the seller.
  • email – An email for the seller.
  • agreement – An optional date that can be used for terms validation. The responsibility to use that date as a validation/expiration is left to the client.

Response

The created seller is returned to you. For example:

{
  "status": "ACTIVE",
  "name": "John",
  "email": "jdoe@example.org",
  "resource_pk": "{seller-uuid}",
  "resource_name": "sellers",
  "resource_uri": "/sellers/{seller-uuid}",
  "agreement": ""
}

In case of an error:

{
  "code": "InvalidArgument",
  "message": "UUID must be supplied."
}
Status Codes:
  • 201 – success.
  • 409 – conflict.

Terms

Once the terms have been approved, they can be set on the seller.

GET /terms/:uuid

Response

You get terms related to a seller object matching :uuid. For example:

{
  "terms": "Terms for seller: John",
  "agreement": "2013-11-19T11:48:49.158Z"
}
Status Codes:
  • 200 – success.

Products

This API allows you to get/create products that can be purchased. It is required that a developer can register multiple products with the payment provider.

GET /products

Request

Parameters:
  • external_id – Filter all products by this external identifier. Since this is only unique per seller, filtering by seller is probably a good idea.
  • seller_id – Filter all products by this seller UUID, the primary key for the seller who owns each product.

Response

A list of products matching your query. For example:

[
  {
    "uuid": "{product-uuid}",
    "external_id": "{product-external-uuid}",
    "seller_id": "{seller-uuid}",
    "active": true,
    "name": "Magical Unicorn",
    "resource_pk": "{product-uuid}",
    "resource_name": "products",
    "resource_uri": "/products/{product-uuid}"
  }, {
  ...
  }
]

In case of an error:

{
  "code": "InvalidArgument",
  "message": "some error"
}
Status Codes:
  • 200 – success.
  • 404 – resource not found.
  • 409 – conflict.
POST /products

Request

Parameters:
  • uuid – A unique ID for the product.
  • external_id – An external identifier for the product. This must be unique per seller but doesn’t need to be unique across the entire system.
  • name – A name to describe the product.
  • seller_id – Primary key of seller who owns this product.

Response

The created product is returned to you. For example:

{
  "uuid": "{product-uuid}",
  "external_id": "{product-external-uuid}",
  "seller_id": "{seller-uuid}",
  "active": true,
  "name": "Magical Unicorn",
  "resource_pk": "{product-uuid}",
  "resource_name": "products",
  "resource_uri": "/products/{product-uuid}"
}

In case of an error:

{
  "code": "InvalidArgument",
  "message": {
    "external_id": "external_id must be unique",
    "seller_id": "zero results for seller_id {wrong-uuid}"
  }
}
Status Codes:
  • 201 – success.
  • 409 – conflict.
GET /products/:uuid

Response

You get a product object matching :uuid. For example:

{
  "uuid": "{product-uuid}",
  "external_id": "{product-external-uuid}",
  "seller_id": "{seller-uuid}",
  "active": true,
  "name": "Magical Unicorn",
  "resource_pk": "{product-uuid}",
  "resource_name": "products",
  "resource_uri": "/products/{product-uuid}"
}
Status Codes:
  • 200 – success.