Introduction

Interacting with the REST API

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.

200 OK:A successful GET on a list or detail endpoint
201 Created:A successful POST to a detail endpoint, resulting in the creation of a new resource. The response will have a Location header with a URI pointing to the new resource. If mCASH identifies a duplicate POST request, which means both the ID chosen by client and data matches that of an earlier request, mCASH will not alter the resource but will give the same response with a Location header pointing to the original resource.
204 No content:A successful PUT (update) or DELETE request.
400 Bad request:
 A malformed request from the client. Typically the schema does not validate for the data supplied in the request body.
404 Not found:The status code for all requests to URLs that do not exist. This also includes detail endpoints that resolve to non-existent resources.
405 Method not allowed:
 Not all endpoints support the entire set of HTTP methods. This status code is returned if the client attempts to use an HTTP method that is not supported by a particular endpoint.
409 Conflict:A conflicting request by the client. This typically happens when the client tries to create a resource with an ID that already exists, or if it tries to create or update a resource with data that violates a uniqueness constraint on one or more resource fields; generally anytime a resource is being updated in conflicting ways, concurrently.

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
    }
}

Callbacks

API clients can associate some resources with a callback_uri in order to enable asynchronous communication between the client and server. At certain events mCASH can trigger a callback to specified callback_uri. E.g. if the callback URI is an HTTP URI, an HTTP POST request will be made to the URI. See Callbacks for a more thorough descriptions of callbacks.

Error Responses

In general the error response body consists of an error_type, an error_description and some error_details. The example below shows the response for validation errors.

POST /test/ HTTP/1.1
HOST: callbackserver.test
Content-Type: application/vnd.mcash.api.merchant.v1+json

{"amount": "-42"}
HTTP/1.1 400 Bad Request
Content-Type: application/vnd.mcash.api.merchant.v1+json

{
  "error_type": "validation_error",
  "error_description": "Your request caused validation errors. Please check your data.",
  "error_details":{"amount": ["Value must be larger than 0"]}
}

The HTTP response code can also hold useful information about the error that occurred, in addition to these fields:

error_type : String : optional : default=null
Type of error.
error_description : String : optional : default=null
Human readable description.
error_details : Json : optional : default=null
Keyed JSON Object structure containing detailed error information, if present. Otherwise null.

Media Type

This documentation defines the vendor-specific media type

application/vnd.mcash.api.merchant.v1+json

We also use

application/vnd.mcash.api.merchant.v1+csv

for transaction logs, and

image/png

for attachments. In general, the form is

application/vnd.mcash.[attachment-type].[version]+[format]

Clients are expected to include media type in the Accept header listing types they understand; the mCASH server responds with the media type in the Content-Type header.

A Note on Merchant API Users

All requests to the Merchant API must include an X-Mcash-User header.† API Users are assigned and created by the Merchant through the Self Service Portal, or by the Integrator using the user endpoint. Each API User has an ID unique to that Merchant and is assigned a shared secret and/or a RSA public key that is used for authentication. A typical use case (and the one we recommend) is assigning separate API Users for each POS in the shop. In another case, the Merchant owns and administrates a central server that acts as a proxy for all POSes: in that case, only one API User is created, and its credentials are used by all POSes when making payment requests. In a third case, an Integrator controls the single proxy server; in that case the Integrator uses the X-Mcash-Integrator header in place of an X-Mcash-User header. It is up to the Merchant (or, as the case may be, the Integrator) how to set this up.

† Except when an Integrator is acting as a proxy on behalf of a Merchant client. In that case, the X-Mcash-Integrator header is used instead. See above.

Versioning

The current major version of the API is v1. Changes within a major version will always be backwards-compatible. New major versions may or may not be backwards compatible with the previous major version. Users will always be duly notified when we bump the major version, and of any changes that might affect backwards-compatibility. You can also refer to the changelog for the most recent updates to the API.