Repository Standards

Appearance

On this page

Informational Endpoints ​

In order to allow the client to retrieve all the necessary information required to facilitate payments and authentication, a Payment Gateway is expected to respond to the following requests.

Advertising Vendor Information ​

GET /v2/info

Example Response:

json
{
	"name": "MyService",
	"icon": "https://myservice.com/icon.png",
	"description": "My awesome service", // Optional
	"call_to_action": { // Optional
		"message": "Sign in to MyService to access all of your purchases",
		"button_text": "Sign In"
	},
	"advisory": { // Optional
		"tos": "https://myservice.com/tos",
		"privacy": "https://myservice.com/privacy-policy"
	}
}

Please note that when making a call-to-action, both the message and button text are required, but the overall field is optional if desired.The same does not apply to advisory, where any and all fields are optional.

TIP

Since authorization will be passed in if authenticated, you may choose to manipulate the response based on the existence or value of the bearer token.

Accessing User Information ​

This is used when trying to view the user's information (only works when authenticated).
GET /v2/user

Example Response:

json
{
	"user": { // All of these fields are optional but recommended
		"name": "John Appleseed",
		"email": "john.appleseed@myservice.com",
		"username": "jappleseed"
	},
	"purchases": [
		"com.foo.package1",
		"com.bar.tweak"
	],
	"buttons": [ // Optional array
		{
			"button_name": "Manage my Account",
			"button_link": "https://myservice.com/account"
		}
	]
}

Listing Paid Packages ​

As a departure from tradition, packages will no longer declare themselves as paid, instead relying on the Payment Gateway to say that it is.

This request is made by the client every time it refreshes the repository, so sending a large amount of data over JSON is acceptable if a repository has many paid packages.
GET /v2/packages?currency=EUR

TIP

Currency is optional, but is a nice consideration for user experience. If a Payment Gateway wants to support multiple currencies, it may use the list outlined by ISO 4217.

If the requested currency isn't available or the request does not have a currency query parameter, the Payment Gateway should default back to the United States Dollar (USD).

Example Response:

json
{
	"currency": "USD",
	"packages": [
		{
			"id": "com.foo.package1",
			"price": "2.99"
		},
		{
			"id": "com.bar.tweak",
			"price": "0.99"
		}
	]
}

Additionally, a client may need to be able to lookup an individual package's price. For this, the request will be slightly modified. GET /v2/packages/[package_identifier]

Example Response:

json
{
	"currency": "USD",
	"id": "com.baz.mypackage",
	"price": "1.49"
}