Skip to content

Commit bbcabaf

Browse files
author
Wick
committed
Merge remote-tracking branch 'origin/dev' into dev
2 parents 7499051 + 3ec4ca5 commit bbcabaf

5 files changed

Lines changed: 286 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,11 @@ At its core, **Netlify CMS** is an open-source React app that acts as a wrapper
4343

4444
1. ### Clone this repo
4545

46-
`git clone https://github.com/SettleForDevelopers/Developer-Docs.git`
46+
`git clone https://github.com/SettleAPI/settle-developer-docs.git`
4747

4848
2. ### Navigate into your newly created Settle API docs directory
4949

50-
`cd settle-api-docs`
50+
`cd settle-developer-docs`
5151

5252
3. ### Install dependencies
5353

‎docs/api/guides/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Settle API Overview
3+
description: Getting started with the Settle API
4+
---
5+
# Getting started with the Settle API
6+
7+
**The Settle API allows merchants in the Settle network to integrate Settle into their payment solutions, such as POS terminals, websites, and mobile apps. The API is a versatile framework of functions to create custom payment flows, with buttons, QR codes, or phone numbers depending on the use case.**
8+
9+
To get started we recommend that you first create a consumer account and a business account in the [Sandbox environment](/sandbox). This allows you to try out Settle and test your integration without having to worry about real money.
10+
11+
You can then follow one of the tutorials or checkout the API references directly.

‎docs/api/guides/introduction/authentication.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Authentication
3+
description: Authentication
4+
---
5+
6+
# Authentication
7+
8+
In the Settle API different authentication levels (auth levels) can be achieved depending on the authentication method being used. In the [API Reference](/api/merchant/) the required level for each endpoint in the API is given. A list is given here of the auth levels in the Settle API, ordered from lowest to highest level:
9+
10+
1. OPEN _(no authentication required)_
11+
2. [SECRET](#authentication-using-secret)
12+
3. [KEY](#authentication-using-rsa-signature)
13+
14+
When authenticated with a particular auth level, the client is also authorized for endpoints requiring a lower auth level. E.g. if authenticated with auth level [KEY](/guides/authentication/#authentication-using-rsa-signature), endpoints requiring [SECRET](/guides/authentication/#authentication-using-secret) or OPEN are also accessible.
15+
16+
## Required Request Headers
17+
18+
Any request to the Settle API requires the following request headers:
19+
20+
| X-Auka-Merchant: | This header should contain the Settle ID of the merchant as returned in the `id` field of the [`merchant`](https://developer.settle.eu/handlers.html#get--merchant--merchant_id-- 'GET /merchant/<merchant_id>/') endpoint. |
21+
| X-Auka-User: | The ID (username) of the user/client doing the request on behalf of the merchant. Users are created by the merchant through the Self Service Portal or by the integrator using the `user` endpoint. Each user has is an ID locally unique for the merchant and is assigned a shared secret and/or a RSA public key that is used for authentication. |
22+
| Authorization: | The value of this field depends on what kind of authentication scheme is being used. Currently the supported schemes are _SECRET_ and _RSA-SHA256_. The general form of this header is: `Authorization: <auth_scheme> <auth_data>` |
23+
| X-Auka-Integrator: | Only to be used by integrators acting as a proxy on behalf of merchant client, in which case it replaces the **X-Auka-User** header. The value of this field is the ID issued to the integrator by Settle. When this header is used only authentication using RSA signatures is allowed (not secret) and Settle will check the signature against the public key of the integrator. |
24+
25+
::: tip NOTE
26+
When using the Settle testbed environment, an **X-Testbed-Token** header is also required. The value of this header is the testbed token you received via email when activating your testbed account. It looks like:
27+
28+
`s_Qu1gkYsZUvK-RvO43Ij02CYV-3wyMp5uUn1AodymQ`
29+
:::
30+
31+
::: tip NOTE
32+
The **X-Auka-Integrator** header MUST NOT be used unless the merchant clients are communicating _through_ a server, controlled by the integrator, acting as a proxy. If a client is using a direct connection to Settle, even though the integrator owns the client and may control it through some other channel, it MUST use merchant user credentials and the **X-Auka-User** header.
33+
:::
34+
35+
## Authentication using SECRET
36+
37+
- Auth Level: SECRET
38+
39+
Authentication using a shared secret (JSON Web Token) is the simplest authentication method supported by Settle. This method requires an authorization header on the following form:
40+
41+
`Authorization: SECRET <secret>`
42+
43+
Below is an example of a request where user **POS1** is doing an **HTTP POST** to **https://sever.test/some/resource/** on behalf of a merchant whose ID is **T9oWAQ3FSl6oeITuR2ZGWA**. The secret is **MySecretPassword** and the request body is `{"text": "Hello world"}`.
44+
45+
```http
46+
POST /some/resource/ HTTP/1.1
47+
HOST: server.test
48+
Accept: application/vnd.mcash.api.merchant.v1+json
49+
Content-Type: application/json
50+
X-Auka-Merchant: T9oWAQ3FSl6oeITuR2ZGWA
51+
X-Auka-User: POS1
52+
Authorization: SECRET MySecretPassword
53+
54+
{"text": "Hello world"}
55+
```
56+
57+
## Authentication using RSA signature
58+
59+
- Auth Level: KEY
60+
61+
Settle generates and validates according to the _PKCS#1 v1.5_ (RSASSA-PKCS1-v1_5) standard described in **[RFC 3447](http://tools.ietf.org/html/rfc3447.html)**. The hash function used in the signing procedure is [SHA256](https://en.wikipedia.org/wiki/SHA-2).
62+
63+
### Headers
64+
65+
The RSA authentication method requires two extra headers:
66+
67+
#### X-Auka-Timestamp
68+
69+
> The current UTC time. The time format is `YYYY-MM-DD hh:mm:ss`.
70+
71+
#### X-Auka-Content-Digest
72+
73+
> The _base64_ encoded hash digest of the request body. If the body is empty, the hash should be computed on an empty string. The value of the header should be on the form `<algorithm (uppercase)>=<digest value>`. So, if the SHA256 hashing algorithm is used on a request with empty body, the header will be: `X-Auka-Content-Digest: SHA256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=` Currently only the SHA256 hashing algorithm is supported.
74+
75+
For RSA authentication the authorization header looks like this:
76+
77+
```http
78+
Authorization: RSA-SHA256 <rsa_signature>
79+
```
80+
81+
The string that is to be signed (the signature message) is constructed from the request in the following manner:
82+
83+
```
84+
<method>|<url>|<headers>
85+
```
86+
87+
Here, `method` is the HTTP method used in the request, `url` is the full url including protocol and query component (the part after `?`) but without fragment component (The part after `#`). The `scheme name` (typically https) and `hostname` components are always lowercase, while the rest of the `url` is case sensitive. The `headers` part is a querystring using header names and values as key-value pairs. So, the constructed string will be of the form:
88+
89+
```
90+
name1=value1&name2=value2...
91+
```
92+
93+
::: tip In addition the following requirements apply:
94+
95+
1. Headers are sorted alphabetically.
96+
2. All header names must be made uppercase before constructing the string.
97+
3. Headers whose names don't start with **X-Auka-** are excluded.
98+
:::
99+
100+
Reusing the example in the previous section, a typical HTTP request will look like this:
101+
102+
```http
103+
POST /some/resource/ HTTP/1.1
104+
HOST: server.test
105+
Accept: application/vnd.mcash.api.merchant.v1+json
106+
Content-Type: application/json
107+
X-Auka-Merchant: T9oWAQ3FSl6oeITuR2ZGWA
108+
X-Auka-User: POS1
109+
X-Auka-Timestamp: 2013-10-05 21:33:46
110+
X-Auka-Content-Digest: SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=
111+
Authorization: RSA-SHA256 p8+PdS5dDa6Ig46jNQhE8qQR+J8rRgX77cyXN3EIvUqpQ2lB8Cz1bcUF6lwvdVbz4NSUIQD/OCT8X2WtqRNbPW+5DDzGC1TytiV6p0EXiMOAl7s6kioHnVGaiCSHyfO6ZYB7ubtcMtUE0+7OEUcPeaqSHeL4wwUkO8W0+euwGsfwl9gOoQHBFIOh0bh8z3JNGhUeIZM8fvrk+8kj/s2A70IBvUOLwcFeP8uf6gTi1fz7BtgJ5rHmfvn9HvrsyO53/nx2mXZdAap4MfOZa6dp0ievZ5kU1vEfB2R6f4uPHzKLnaePlDOQMTk+uHlxU0ChkSqenbgJvpGuaOGiQekwsA==
112+
113+
{"text": "Hello world"}
114+
```
115+
116+
In this case the header part of the signature message is:
117+
118+
```http
119+
X-AUKA-CONTENT-DIGEST=SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=&X-AUKA-MERCHANT=T9oWAQ3FSl6oeITuR2ZGWA&X-AUKA-TIMESTAMP=2013-10-05 21:33:46&X-AUKA-USER=POS1
120+
```
121+
122+
and complete signature message is:
123+
124+
```http
125+
POST|http://server.test/some/resource/|X-AUKA-CONTENT-DIGEST=SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=&X-AUKA-MERCHANT=T9oWAQ3FSl6oeITuR2ZGWA&X-AUKA-TIMESTAMP=2013-10-05 21:33:46&X-AUKA-USER=POS1
126+
```
127+
128+
The key-pair that was used for generating the signature in this example can be downloaded here: [`public`](https://developer.settle.eu/_downloads/sample-pubkey.pem), [`private`](https://developer.settle.eu/_downloads/sample-privkey.pem)
129+
130+
The Python script that was used for generating the signature and `X-Auka-Content-Digest` header can be downloaded [`here`](https://developer.settle.eu/_downloads/rsa_example.py)
131+
132+
## Verifying signatures from Settle
133+
134+
Whenever Settle is sending callbacks to the client over HTTPS the request from Settle is signed using the same RSA method as described in the above _[section](/guides/authentication/#authentication-using-rsa-signature)_. The client should authenticate callbacks from Settle by verifying the signature given by Settle in the Authorization header of the request. The public key used by Settle in test environments can be downloaded [`here`](https://developer.settle.eu/_downloads/testserver-pub.pem). The public key for the production environment can be obtained by contacting Settle.

‎docs/api/guides/introduction/interacting.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: 1. Interacting with the REST API's
3+
description: How to interact with the Settle REST API's
4+
---
5+
# Creating, Retrieving, Updating and Deleting resources (CRUD)
6+
7+
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):
8+
9+
`/my_resource/`
10+
11+
A detail endpoint looks like this:
12+
13+
`/my_resource/<id>/`
14+
15+
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 Settle.
16+
17+
A few examples:
18+
19+
`https://api.settle.eu/merchant/v1/pos/`
20+
21+
is a list endpoint for POSes. This URI:
22+
23+
`https://api.settle.eu/merchant/v1/pos/12/`
24+
25+
is the detail endpoint for the POS with id 12.
26+
27+
Note that all URLs have a trailing slash by convention.
28+
29+
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:
30+
31+
`https://api.settle.eu/merchant/v1/pos/3y987j9o4o23/`
32+
33+
In this documentation we'll sometimes leave out the version bit:
34+
35+
`/merchant/v1/`
36+
37+
when specifying endpoint URLs, for brevity's sake.
38+
39+
## List endpoints
40+
41+
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.
42+
43+
```http
44+
GET /merchant/ HTTP/1.1
45+
HOST: server.test
46+
Accept: application/vnd.mcash.api.merchant.v1+json
47+
```
48+
49+
```http
50+
HTTP/1.1 200 OK
51+
Content-Type: application/vnd.mcash.api.merchant.v1+json
52+
53+
{
54+
"uris": ["/merchant/abc1/", "/merchant/abc2/", "/merchant/abc3/"],
55+
"next": "/merchant/?next=asDFgh"
56+
}
57+
```
58+
59+
## Response status codes
60+
61+
Listed below are the most common http response status codes and what they mean in the Settle API.
62+
63+
| **200 OK:** | A successful GET on a list or detail endpoint |
64+
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65+
| **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 Settle identifies a duplicate POST request, which means both the ID chosen by client and data matches that of an earlier request, Settle will not alter the resource but will give the same response with a `Location` header pointing to the original resource. |
66+
| **204 No content:** | A successful PUT (update) or DELETE request. |
67+
| **400 Bad request:** | A malformed request from the client. Typically the schema does not validate for the data supplied in the request body. |
68+
| **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. |
69+
| **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. |
70+
| **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. |
71+
72+
Certain endpoints might return other status codes than those listed here. Special cases are covered in the *[Settle API Reference](https://developer.settle.eu/handlers.html)*.
73+
74+
## Schema definitions
75+
76+
All resources in the Settle API are documented in the *[Settle API Reference](https://developer.settle.eu/handlers.html)*, 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`](https://developer.settle.eu/handlers.html#post--pos- "POST /pos/") method as an example. This method defines the following input schema:
77+
78+
### `name`
79+
80+
String : required
81+
82+
* length <= 100
83+
* Data required (new or existing on update)
84+
85+
Human-readable name of the POS, used for displaying payment request origin to end user.
86+
87+
### `type`
88+
89+
String : required
90+
91+
* length <= 50
92+
* Value in store, webshop, mobile, vending, poster.
93+
* Data required (new or existing on update).
94+
95+
POS type.
96+
97+
### `location`
98+
99+
[Location](https://developer.settle.eu/types.html#wtforms-fielddoc-handlers-7) : optional : default=null
100+
101+
Merchant location.
102+
103+
### `id`
104+
105+
String : required
106+
107+
* length <= 100
108+
* Data required (new or existing on update)
109+
110+
The ID of the POS that is to be created. Has to be unique for the merchant.
111+
112+
113+
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.
114+
115+
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 behavior, e.g. the [Money](https://developer.settle.eu/types.html#wtforms-fielddoc-oauth_api-0) type; more commonly they have a nested structure like in this example. Clicking the [Location](https://developer.settle.eu/types.html#wtforms-fielddoc-handlers-7) link leads us to the following schema definition.
116+
117+
| **latitude** : Float : optional : default=null | Latitude |
118+
| ----------------------------------------------- | ------------------- |
119+
| **longitude** : Float : optional : default=null | Longitude |
120+
| **accuracy** : Float : optional : default=null | Accuracy in meters. |
121+
122+
123+
124+
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:
125+
126+
```json
127+
{
128+
"id": "POS1",
129+
"name": "My first POS",
130+
"type": "store",
131+
"location": {
132+
"latitude": 59.0,
133+
"longitude": 10.0,
134+
"accuracy": 20.0
135+
}
136+
}

‎yarn.lock‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6107,9 +6107,9 @@ postcss-value-parser@^4.0.2, postcss-value-parser@^4.1.0:
61076107
integrity sha512-97DXOFbQJhk71ne5/Mt6cOu6yxsSfM0QGQyl0L25Gca4yGWEGJaig7l7gbCX623VqTBNGLRLaVUCnNkcedlRSQ==
61086108

61096109
postcss@^7.0.0, postcss@^7.0.1, postcss@^7.0.14, postcss@^7.0.26, postcss@^7.0.27, postcss@^7.0.32, postcss@^7.0.5, postcss@^7.0.6:
6110-
version "7.0.35"
6111-
resolved "https://registry.yarnpkg.com/postcss/-/postcss-7.0.35.tgz#d2be00b998f7f211d8a276974079f2e92b970e24"
6112-
integrity sha512-3QT8bBJeX/S5zKTTjTCIjRF3If4avAT6kqxcASlTWEtAFCb9NH0OUxNDfgZSWdP5fJnBYCMEWkIFfWeugjzYMg==
6110+
version "7.0.36"
6111+
resolved "https://registry.yarnpkg.com/postcss/-/postcss-7.0.36.tgz#056f8cffa939662a8f5905950c07d5285644dfcb"
6112+
integrity sha512-BebJSIUMwJHRH0HAQoxN4u1CN86glsrwsW0q7T+/m44eXOUAxSNdHRkNZPYz5vVUbg17hFgOQDE7fZk7li3pZw==
61136113
dependencies:
61146114
chalk "^2.4.2"
61156115
source-map "^0.6.1"

0 commit comments

Comments
 (0)