Introduction¶

Creating, Retrieving, Updating and Deleting resources (CRUD)¶

Resources are created by making an HTTP POST request to a list endpoint, and updated by PUTting to the detail endpoint of the created resource. Resource data is retrieved using GET and deleted using DELETE, both to the detail endpoint. Making a GET request to a list endpoint that supports it yields a list of URLs to detail endpoints for the resources of that particular resource type. A list endpoint URI is of the following form (host and API version prefix not included):

/my_resource/

A detail endpoint looks like this:

/my_resource/<id>/

where <id> is the ID of the resource residing at this endpoint. In cases where an id field is specified in the input schema for resource creation, the value of <id> will be the id of the created resource. Otherwise the ID is generated by mCASH.

A few examples:

https://api.mca.sh/merchant/v1/pos/

is a list endpoint for POSes. This URI:

https://api.mca.sh/merchant/v1/pos/12/

is the detail endpoint for the POS with id 12.

Note that all URLs have a trailing slash by convention.

URIs returned in Location headers are full URLs. The URIs returned by the API in JSON responses are absolute relative URIs, without server hostname. It's up to you to prepend hostname and protocol. A complete URL looks like this:

https://api.mca.sh/merchant/v1/pos/3y987j9o4o23/

In this documentation we'll sometimes leave out the version bit:

/merchant/v1/

when specifying endpoint URLs, for brevity's sake.

List endpoints¶

List endpoints are associated with a resource class. Unless otherwise specified, a GET on a list endpoint will return a list of URIs that point to resources of its particular class, together with a cursor called next. The cursor points to the next list endpoint with more resources, and another next cursor. And so on.

GET /merchant/ HTTP/1.1
HOST: server.test
Accept: application/vnd.mcash.api.merchant.v1+json

HTTP/1.1 200 OK
Content-Type: application/vnd.mcash.api.merchant.v1+json

{
    "uris": ["/merchant/abc1/", "/merchant/abc2/", "/merchant/abc3/"],
    "next": "/merchant/?next=asDFgh"
}

Response status codes¶

Listed below are the most common http response status codes and what they mean in the Merchant API.

Certain endpoints might return other status codes than those listed here. Special cases are covered in the Merchant API Reference.

Schema definitions¶

All resources in the Merchant API are documented in the Merchant API Reference, with input and output schemas definitions, with the expected structure of input and output data for the respective API calls. To explain what these schemas mean, let's look at the POS creation method as an example. This method defines the following input schema:

name : String : required length <= 100 Data required (new or existing on update)	Human-readable name of the POS, used for displaying payment request origin to end user
type : String : required length <= 50 Value in store, webshop, mobile, vending, poster Data required (new or existing on update)	POS type
location : Location : optional : default=null	Merchant location
id : String : required Data required (new or existing on update) length <= 100	The ID of the POS that is to be created. Has to be unique for the merchant

The schema is represented as a two-column table where each row represents a field (i.e. a JSON field) in the data format. For each row the right column contains a descriptive text about the field, contains the field name and lists the various constraints that apply to the field. The first line in the left column contains field name, type (e.g. String), whether the field is optional or required, and the default value for optional fields.

The location field of the example schema has a field type (Location) that is linked to another schema definition-- it is a Complex Type. Complex Types can be single-value types with some special behaviour, e.g. the Money type; more commonly they have a nested structure like in this example. Clicking the Location link leads us to the following schema definition.

latitude : Float : optional : default=null	Latitude
longitude : Float : optional : default=null	Longitude
accuracy : Float : optional : default=null	Accuracy in meters.

This means that the location field is a nested structure composed of three other fields-- latitude, longitude and accuracy-- that together represent geographic coordinates. This is best illustrated with an example JSON object that validates for the POS creation input schema:

{
    "id": "POS1",
    "name": "My first POS",
    "type": "store",
    "location": {
        "latitude": 59.0,
        "longitude": 10.0,
        "accuracy": 20.0
    }
}