Payments

This API is specific to setting up and processing payments for an app in the Marketplace.

Configuring payment accounts

Payment accounts can be added and listed.

Note

Authentication is required.

POST /api/v2/payments/account/

Request

Parameters:
  • account_name (string) – Account name.
  • companyName (string) – Company name.
  • vendorName (string) – Vendor name.
  • financeEmailAddress (string) – Financial email.
  • supportEmailAddress (string) – Support email.
  • address1 (string) – Address.
  • address2 (string) – Second line of address.
  • addressCity (string) – City/municipality.
  • addressState (string) – State/province/region.
  • addressZipCode (string) – Zip/postal code.
  • countryIso (string) – Country.
  • vatNumber (string) – VAT number.

the following fields cannot be modified after account creation

Parameters:
  • bankAccountPayeeName (string) – Account holder name.
  • bankAccountNumber (string) – Bank account number.
  • bankAccountCode (string) – Bank account code.
  • bankName – Bank name.
  • bankAddress1 (string) – Bank address.
  • bankAddress2 (string) – Second line of bank address.
  • bankAddressState (string) – Bank state/province/region.
  • bankAddressZipCode (string) – Bank zip/postal code.
  • bankAddressIso (string) – Bank country.
  • adminEmailAddress (string) – Administrative email.
  • currencyIso (string) – Currency you prefer to be paid in.

Response

Status:201 successfully created.
PUT /api/v2/payments/account/(int: id)/

Request

Parameters:
  • account_name (string) – Account name.
  • vendorName (string) – Vendor name.
  • financeEmailAddress (string) – Financial email.
  • supportEmailAddress (string) – Support email.
  • address1 (string) – Address.
  • address2 (string) – Second line of address.
  • addressCity (string) – City/municipality.
  • addressState (string) – State/province/region.
  • addressZipCode (string) – Zip/postal code.
  • countryIso (string) – Country.
  • vatNumber (string) – VAT number.

Response

Status Codes:
DELETE /api/v2/payments/account/(int: id)/

Warning

This can potentially remove all your apps from sale.

If you delete a payment account then all apps which use that account can no longer process payments. All apps that use this payment account will be moved into the incomplete state. Each of those apps will need to resubmitted to process payments.

Response

Status Codes:
GET /api/v2/payments/account/

Request

The standard Listing query params.

Response

Parameters:
GET /api/v2/payments/account/(int: id)/

Response

An account object, see below for an example.

Status Codes:
  • 200 OK – successfully completed.

Example:

{
     "account_name": "account",
     "address1": "123 Main St",
     "addressCity": "Byteville",
     "addressPhone": "605-555-1212",
     "addressState": "HX",
     "addressZipCode": "55555",
     "adminEmailAddress": "[email protected]",
     "companyName": "Example Company",
     "countryIso": "BRA",
     "currencyIso": "EUR",
     "financeEmailAddress": "[email protected]",
     "resource_uri": "/api/v2/payments/account/175/",
     "supportEmailAddress": "[email protected]",
     "vendorName": "vendor"
}

Upsell

POST /api/v2/payments/upsell/

Creates an upsell relationship between two apps, a free and premium one. Send the URLs for both apps in the post to create the relationship.

Request

Parameters:
  • free (string) – URL to the free app.
  • premium (string) – URL to the premium app.

Response

Status Codes:
GET /api/v2/payments/upsell/(int: id)/

Response

{"free": "/api/v2/apps/app/1/",
 "premium": "/api/v2/apps/app/2/"}
Parameters:
  • free (string) – URL to the free app.
  • premium (string) – URL to the premium app.
PATCH /api/v2/payments/upsell/(int: id)/

Alter the upsell from free to premium by passing in new free and premiums.

Request

Parameters:
  • free (string) – URL to the free app.
  • premium (string) – URL to the premium app.

Response

Status Codes:
  • 200 OK – sucessfully altered.
DELETE /api/v2/payments/upsell/(int: id)/

To delete the upsell relationship.

Response

Status Codes:

In-app products

In-app products are used for setting up in-app payments without the need to host your own JWT signer. This API is for managing your in-app products for use with the in-app payment service.

The origin refers to the origin of the packaged app. For example: app://foo-app.com.

Note

Feature not complete.

POST /api/v2/payments/(string: origin)/in-app/

Note

Authentication is required.

Creates a new in-app product for sale.

Request

Parameters:
  • name (string) –

    Product names as an object of localizations, serialized to JSON. Example:

    {"en-us": "English product name",
 "pl": "polska nazwa produktu"}

    The object keys must be lower case codes in the IETF language tag format.

  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.

Response

Status Codes:
Parameters:
  • guid (string) – A globally unique ID for this in-app product.
  • app (string) – The slug for the app.
  • name (string) – The name for the in-app product.
  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.
GET /api/v2/payments/(string: origin)/in-app/

List the in-app products for this app.

Request

None

Response

Status Codes:
  • 200 OK – successfully completed.
Parameters:
  • guid (string) – The in-app product ID.
  • app (string) – The slug for the app.
  • name (string) – The name for the in-app product.
  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.
GET /api/v2/payments/(string: origin)/in-app/(string: id)/

Details of an in-app product.

Request

Parameters:
  • active (string) – include active products, if ignored all in-app products are returned. Value should be one of 0 or 1.

Response

Status Codes:
  • 200 OK – successfully completed.
Parameters:
  • guid (string) – The in-app product ID.
  • app (string) – The slug for the app.
  • name (string) – The name for the in-app product.
  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.
PUT /api/v2/payments/(string: origin)/in-app/(string: id)/

Note

Authentication is required.

Update an in-app product.

Request

Parameters:
  • name (string) –

    Product names as an object of localizations, serialized to JSON. Example:

    {"en-us": "English product name",
 "pl": "polska nazwa produktu"}

    The object keys must be lower case codes in the IETF language tag format.

    IMPORTANT: Any string for a new locale will not overwrite strings in existing locales. If you want to delete an older locale, you need to set it to null like {"en-us": null, "pl": "..."}.

  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.

Response

Status Codes:
  • 200 OK – successfully completed.
Parameters:
  • guid (string) – The in-app product ID.
  • app (string) – The slug for the app.
  • name (string) – The name for the in-app product.
  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.
GET /api/v2/payments/stub-in-app-products/

List some stub in-app products that can be used for testing. These products can only be purchased in simulation mode.

Request

None

Response

{
    "meta": {
        "limit": 25,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "app": null,
            "guid": "d3182953-feed-44dd-a3be-e17ae7fe6a2c",
            "logo_url": "https://marketplace.cdn.mozilla.net/media/img/developers/simulated-kiwi.png",
            "name": "Kiwi",
            "price_id": 237
        },
        {
            "app": null,
            "guid": "8b3fa156-354a-47a9-b862-0f02b56d0e3d",
            "logo_url": "https://marketplace.cdn.mozilla.net/media/img/mkt/icons/rocket-64.png",
            "name": "Rocket",
            "price_id": 238
        }
    ]
}
Status Codes:
  • 200 OK – successfully completed.
Objects:

list of stub products. See get stub product.
GET /api/v2/payments/stub-in-app-products/(string: guid)/

Get detailed info for a specific stub product.

Request

None

Response

Status Codes:
  • 200 OK – successfully completed.
Parameters:
  • guid (string) – The in-app product ID.
  • name (string) – The name for the in-app product.
  • logo_url (string) – URL to a logo for the product.
  • price_id (int) – ID for the price tier.

Preparing payment

Produces the JWT for purchasing an app that is passed to navigator.mozPay.

Note

Authentication is required.

POST /api/v2/webpay/prepare/

Request

Parameters:
  • app (string) – the id or slug of the app to be purchased.

Response

{
    "app": "337141: Something Something Steamcube!",
    "contribStatusURL": "https://marketplace.firefox.com/api/v2/webpay/status/123/",
    "resource_uri": "",
    "webpayJWT": "eyJhbGciOiAiSFMy... [truncated]",
}
Parameters:
Status Codes:

Produces the JWT for purchasing an in-app product that is passed to navigator.mozPay.

Note

Feature not complete.

Note

Authentication is not required or supported.

POST /api/v2/webpay/inapp/prepare/

Request

Parameters:
  • inapp (string) – the guid the in-app product to be purchased.

Response

{
    "contribStatusURL": "https://marketplace.firefox.com/api/v2/webpay/status/123/",
    "webpayJWT": "eyJhbGciOiAiSFMy... [truncated]",
}
Parameters:
Status Codes:

Signature Check

Retrieve a JWT that can be used to check the signature for making payments. This is intended for system health checks and requires no authorization. You can pass the retrieved JWT to the WebPay API to verify its signature.

POST /api/v2/webpay/sig_check/

Request

No parameters are necessary.

Response

{
    "sig_check_jwt": "eyJhbGciOiAiSFMyNT...XsgG6JKCSw"
}
Parameters:
  • sig_check_jwt (string) – a JWT that can be passed to WebPay.
Status Codes:

Payment status

GET /api/v2/webpay/status/(string: uuid)/

Request

Parameters:
  • uuid (string) – the uuid of the payment. This URL is returned as the contribStatusURL parameter of a call to prepare.

Response

Parameters:

Example:

{"status": "complete",
 "receipt": null}

In-app purchases will include a receipt:

{"status": "complete",
 "receipt": "eyJhbGciOiAiUlM1MTI...0Xg0EQfUfH121U7b_tqAYaY"}
Status Codes:
  • 200 OK – request processed, check status for value.

Installing

When an app is installed from the Marketplace, call the install API. This will record the install.

Free apps

POST /api/v2/installs/record/

Request:

Parameters:
  • app (int|string) – the id or slug of the app being installed.

Response:

Status Codes:
  • 201 Created – successfully completed.
  • 202 Accepted – an install was already recorded for this user and app, so we didn’t bother creating another one.
  • 403 Forbidden – app is not public, install not allowed.

Premium apps

Note

Authentication is required.

POST /api/v2/receipts/install/

Returns a receipt if the app is paid and a receipt should be installed.

Request:

Parameters:
  • app (int|string) – the id or slug of the app being installed.

Response:

{"receipt": "eyJhbGciOiAiUlM1MT...[truncated]"}
Status Codes:

Developers

Developers of the app will get a special developer receipt that is valid for 24 hours and does not require payment. See also Test Receipts.

Reviewers

Reviewers should not use this API.

Receipt Testing

Returns test receipts for use during testing or development. The returned receipt will have type test-receipt. Only works for hosted apps.

POST /api/v2/receipts/test/

Returns a receipt suitable for testing your app.

Request:

Parameters:
  • manifest_url (string) – the fully qualified URL to the manifest, including protocol.
  • receipt_type (string) – one of ok, expired, invalid or refunded.

Response:

{"receipt": "eyJhbGciOiAiUlM1MT...[truncated]"}
Status Codes:

Receipt reissue

Takes an expired receipt and returns a reissued receipt with updated expiry times.

POST /api/v2/receipts/reissue/

Request

Param:the body of the request must contain the receipt, in the same way that the receipt verification endpoint does.

Response:

For a good response:

{
    "reason": "",
    "receipt": "eyJhbGciOiAiUlM1MT...[truncated]",
    "status": "expired"
}

For a failed response:

{
    "reason": "NO_PURCHASE",
    "receipt": "",
    "status": "invalid"
}
Parameters:
  • reason (string) – only present if the request failed, contains the reason for failure, see receipt verification docs.
  • receipt (string) – the receipt, currently blank.
  • status (string) – one of ok, expired, invalid, pending, refunded
Status Codes:
  • 200 OK – successfully completed.
  • 400 Bad Request – the receipt was not valid or not in an expired state, examine the response to see the cause. The messages and the causes are the same as for receipt verification.

Price Tiers

GET /api/v2/webpay/prices/

Gets a list of pay tiers from the Marketplace.

Request

Parameters:
  • provider (string) – (optional) the payment provider. Current values: bango

The standard Listing query params.

Response

Parameters:
Status Codes:
  • 200 OK – successfully completed.
GET /api/v2/webpay/prices/(int: id)/

Returns a specific pay tier.

Response

{
    "name": "Tier 1",
    "pricePoint": "1",
    "prices": [{
        "price": "0.99",
        "method": 2,
        "region": 2,
        "tier": 26,
        "provider": 1,
        "currency": "USD",
        "id": 1225,
        "dev": true,
        "paid": true
    }, {
        "price": "0.69",
        "method": 2,
        "region": 14,
        "tier": 26,
        "provider": 1,
        "currency": "DE",
        "id": 1226,
        "dev": true,
        "paid": true
    }],
    "localized": {},
    "resource_uri": "/api/v2/webpay/prices/1/",
    "created": "2011-09-29T14:15:08",
    "modified": "2013-05-02T14:43:58"
}
Parameters:
  • region (int) – a region.
  • carrier (int) – a carrier.
  • localized (object) – see Localized tier.
  • tier (int) – the id of the tier.
  • method (int) – the payment method.
  • provider (int) – the payment provider.
  • pricePoint (string) – this is the value used for in-app payments.
  • dev (boolean) – if true the tier will be shown to the developer during app configuration.
  • paid (boolean) – if true this tier can be used for payments by users.
Status Codes:
  • 200 OK – successfully completed.

Payment methods:

  • 0 Carrier billing only
  • 1 Credit card only
  • 2 Both carrier billing and credit card

Provider:

  • 0 Paypal, not currently supported
  • 1 Bango
  • 2 Reference implementation, not currently supported outside of development instances
  • 3 Boku

Localized tier

To display a price to your user, it would be nice to know how to display a price in the app. The Marketplace does some basic work to calculate the locale of a user. Information that would be useful to show to your user is placed in the localized field of the result.

A request with the HTTP Accept-Language header set to pt-BR, means that localized will contain:

{
    "localized": {
        "amount": "10.00",
        "currency": "BRL",
        "locale": "R$10,00",
        "region": "Brasil"
    }
}

The exact same request with an Accept-Language header set to en-US returns:

{
    "localized": {
        "amount": "0.99",
        "currency": "USD",
        "locale": "$0.99",
        "region": "United States"
    }
}

If a suitable currency for the region given in the request cannot be found, the result will be empty. It could be that the currency that the Marketplace will accept is not the currency of the country. For example, a request with Accept-Language set to fr may result in:

{
    "localized": {
        "amount": "1.00",
        "currency": "USD",
        "locale": "1,00\xa0$US",
        "region": "Monde entier"
    }
}

Please note: these are just examples to demonstrate cases. Actual results will vary depending upon data sent and payment methods in the Marketplace.

Product Icons

Authenticated clients like WebPay need to display external product images in a safe way. This API lets WebPay cache and later retrieve icon URLs.

Note

All write requests (POST, PATCH) require authenticated users to have the ProductIcon:Create permission.

GET /api/v2/webpay/product/icon/

Gets a list of cached product icons.

Request

Parameters:
  • ext_url (string) – Absolute external URL of product icon that was cached.
  • ext_size (int) – Height and width pixel value that was declared for this icon.
  • size – Height and width pixel value that this icon was resized to.

You may also request Listing query params.

Response

Parameters:
Status Codes:
  • 200 OK – successfully completed.
GET /api/v2/webpay/product/icon/(int: id)/

Response

{
    "url": "http://marketplace-cdn/product-icons/0/1.png",
    "resource_uri": "/api/v2/webpay/product/icon/1/",
    "ext_url": "http://appserver/media/icon.png",
    "ext_size": 64,
    "size": 64
}
Parameters:
  • url (string) – Absolute URL of the cached product icon.
Status Codes:
  • 200 OK – successfully completed.
POST /api/v2/webpay/product/icon/

Post a new product icon URL that should be cached. This schedules an icon to be processed but does not return any object data.

Request

Parameters:
  • ext_url (string) – Absolute external URL of product icon that should be cached.
  • ext_size (int) – Height and width pixel value that was declared for this icon.
  • size (int) – Height and width pixel value that this icon should be resized to.

Response

Status Codes:

Transaction failure

Note

Requires authenticated users to have the Transaction:NotifyFailure permission. This API is used by internal clients such as WebPay.

PATCH /api/v2/webpay/failure/(int: transaction_id)/

Notify the app developers that our attempts to call the postback or chargebacks URLs from In-app Payments failed. This will send an email to the app developers.

Response

Status Codes: