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/v1/payments/account/¶

Request

Parameters:

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.

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:

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.

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 Codes:	code – 201 successfully created.

PUT /api/v1/payments/account/(int: id)/¶

Request

Parameters:

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.

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.

Response

Status Codes:	204 – successfully updated.

DELETE /api/v1/payments/account/(int: id)/¶

Response

Status Codes:	204 – successfully deleted.

GET /api/v1/payments/account/¶

Request

The standard Listing query params.

Response

Parameters:	meta (object) – Listing response meta. objects (array) – A listing of accounts.

GET /api/v1/payments/account/(int: id)/¶

Response

An account object, see below for an example.

Status Codes:	200 – successfully completed.

Example:

{
     "account_name": "account",
     "address1": "123 Main St",
     "addressCity": "Byteville",
     "addressPhone": "605-555-1212",
     "addressState": "HX",
     "addressZipCode": "55555",
     "adminEmailAddress": "apps_admin@example.com",
     "companyName": "Example Company",
     "countryIso": "BRA",
     "currencyIso": "EUR",
     "financeEmailAddress": "apps_accounts@example.com",
     "resource_uri": "/api/v1/payments/account/175/",
     "supportEmailAddress": "apps_support@example.com",
     "vendorName": "vendor"
}

Upsell¶

POST /api/v1/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:	201 – sucessfully created.

GET /api/v1/payments/upsell/(int: id)/¶

Response

{"free": "/api/v1/apps/app/1/",
 "premium": "/api/v1/apps/app/2/"}

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

PATCH /api/v1/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 – sucessfully altered.

DELETE /api/v1/payments/upsell/(int: id)/¶

To delete the upsell relationship.

Response

Status Codes:	204 – sucessfully deleted.

Payment accounts¶

POST /api/v1/payments/app/¶

Creates a relationship between the payment account and the app.

Request

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

Once created, the app is not changeable.

Response

Status Codes:	201 – sucessfully created.
Parameters:	app (string) – URL to the premium app. account (string) – URL to the account.

PATCH /api/v1/payments/app/(int: id)/¶

Alter the payment account being used.

Request

Parameters:	app (string) – URL to the premium app. Must be unchanged. account (string) – URL to the account.

Response

Status Codes:	200 – sucessfully updated.
Parameters:	app (string) – URL to the premium app. account (string) – URL to the account.

Preparing payment¶

Produces the JWT that is passed to navigator.mozPay.

Note

Authentication is required.

POST /api/v1/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/v1/webpay/status/123/",
    "resource_uri": "",
    "webpayJWT": "eyJhbGciOiAiSFMy... [truncated]",
}

Parameters:	webpayJWT (string) – the JWT to pass to navigator.mozPay contribStatusURL (string) – the URL to poll for Payment status.
Status Codes:	201 – successfully completed. 401 – not authenticated. 403 – app cannot be purchased. 409 – app already purchased.

Payment status¶

Note

Authentication is required.

GET /api/v1/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:	status (string) – `complete` or `incomplete`
Status Codes:	200 – request processed, check status for value. 403 – not authorized to view details on that transaction.

Installing¶

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

Free apps¶

POST /api/v1/installs/record/¶

Request:

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

Response:

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

Premium apps¶

POST /api/v1/receipts/install/¶

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

Request:

Parameters:	app – the id or slug of the app being installed.

:type app : int|string

Response:

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

Status Codes:	201 – successfully completed. 402 – payment required. 403 – app is not public, install not allowed.

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.

Test Receipts¶

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

POST /api/v1/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:	201 – successfully completed.

Receipt reissue¶

This is currently not implemented awaiting bug. It will be used for replacing receipts.

POST /api/v1/receipts/reissue/¶

Response:

{"receipt": "", "status": "not-implemented"}

Parameters:	receipt (string) – the receipt, currently blank. status (string) – one of `not-implemented`.
Status Codes:	200 – successfully completed.

Pay Tiers¶

GET /api/v1/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:	meta (object) – Listing response meta. objects (array) – A listing of apps.
Status Codes:	200 – successfully completed.

GET /api/v1/webpay/prices/(int: id)/¶

Response

{
    "name": "Tier 1",
    "pricePoint": "1",
    "prices": [{
        "price": "0.99",
        "method": 2,
        "region": 2,
        "tier": 26,
        "provider": 1,
        "currency": "USD",
        "id": 1225
    }, {
        "price": "0.69",
        "method": 2,
        "region": 14,
        "tier": 26,
        "provider": 1,
        "currency": "DE",
        "id": 1226
    }],
    "localized": {},
    "resource_uri": "/api/v1/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) – payment provider, currently only `1` is supported. pricePoint (string) – this is the value used for in-app payments.
Status Codes:	200 – successfully completed.

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/v1/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:	meta (object) – Listing response meta. objects (array) – A listing of product icons.
Status Codes:	200 – successfully completed.

GET /api/v1/webpay/product/icon/(int: id)/¶

Response

{
    "url": "http://marketplace-cdn/product-icons/0/1.png",
    "resource_uri": "/api/v1/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 – successfully completed.

POST /api/v1/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:	202 – New icon accepted. Deferred processing will begin. 400 – Some required fields were missing or invalid. 401 – The API user is unauthorized to cache product icons.

Transaction failure¶

Note

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

PATCH /api/v1/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:	202 – Notification will be sent. 401 – The API user is not authorized to report failures.

Table of Contents

Payments¶

Configuring payment accounts¶

Upsell¶

Payment accounts¶

Preparing payment¶

Payment status¶

Installing¶

Free apps¶

Premium apps¶

Developers¶

Reviewers¶

Test Receipts¶

Receipt reissue¶

Pay Tiers¶

Product Icons¶

Transaction failure¶