Skip to content

Commit b638d98

Browse files
rexgnurexgnu
authored
Merge pull request #30 from SettleAPI/gabriel-added-How-to-integrate-a-webshop
Gabriel added how to integrate a webshop
2 parents c765681 + 31d1159 commit b638d98

2 files changed

Lines changed: 187 additions & 10 deletions

File tree

‎guide/How-to-integrate-a-webshop.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
tags: [guide, shortlink, qr]
3+
internal: true
4+
---
5+
6+
# How to integrate a webshop
7+
8+
**In this tutorial we will integrate is a generic web shop that uses a custome ecommerce point of sale system, which allows their staff to accept payments at customers' tables. They accept cash, card and Settle.**
9+
10+
When a client wishes to pay with Settle, the POS generates a QR code for the customer to scan, which is used by the POS vendor to initiate a payment request.
11+
12+
### 1. Generating the QR code
13+
14+
The POS generates and displays a QR code which contains the **shortlink ID** and a **transaction ID** generated by the vendor's backend system.
15+
16+
Settle expects a scanned QR code to contain a specific URL:
17+
18+
```
19+
http://settle.eu/s/<shortlink_id>/<vendors_transaction_id>
20+
```
21+
22+
Note that _<http://settle.eu/s/>\<shortlink_id>/_ is mandatory, the rest of the URL (_vendors_transaction_id_) will be sent to the callback handler.
23+
24+
### 2. QR code scan
25+
26+
When the customer scans the QR code and the scan is registered by Settle, Settle generates a unique _[scan token](https://developer.settle.eu/callbacks.html#callbacks-shortlink)_ which can be used by the vendor's backend system to initiate a payment request.
27+
28+
### 3. Callback
29+
30+
Settle calls the vendor's specified _callback_uri_, passing in the _scan token_ which can be used to create a payment request. The 'extra' information encoded in the QR code (_vendors_transaction_id_ in this example) is also present in the payload.
31+
32+
The following is an example of the payload that would be sent to the vendor's backend when a QR code containing `http://settle.eu/s/<shortlink_id>/<vendors_transaction_id>` is scanned:
33+
34+
```json
35+
{
36+
"meta": {
37+
"seqno": 0,
38+
"labels": [
39+
40+
],
41+
"uri": null,
42+
"id": "D5S6WYjnQ_ObT-DyZfrVPA",
43+
"context": "ctx:D5S6WYjnQ_ObT-DyZfrVPA",
44+
"timestamp": "2019-03-21 08:58:49",
45+
"event": "shortlink_scanned"
46+
},
47+
"object": {
48+
"id": "token:5632006343884800",
49+
"argstring": "vendors_transaction_id"
50+
}
51+
}
52+
```
53+
54+
The _scan token_ for this scan is `token:5632006343884800`.
55+
56+
### 4. Payment request
57+
58+
The vendor initiates a [`payment request`](https://developer.settle.eu/handlers.html#post--payment_request- "POST /payment_request/") using the _[scan token](https://developer.settle.eu/callbacks.html#callbacks-shortlink)_ that Settle generated as the value in the `customer` field.
59+
60+
Example payment request for €20, using the _scan token_ from the previous section:
61+
62+
```json
63+
// POST https://api.settle.demo/merchant/v1/payment_request/
64+
65+
{
66+
"action": "SALE",
67+
"allow_credit": true,
68+
"pos_tid": "vendors_transaction_id",
69+
"pos_id": "id-of-the-pos",
70+
"customer": "token:5632006343884800",
71+
"currency": "EUR",
72+
"amount": 2000
73+
}
74+
```
75+
76+
Example response:
77+
78+
```json
79+
{
80+
"id": "p2ybyw4tq73n",
81+
"uri": null
82+
}
83+
```
84+
85+
Note that the `id` field in the response is Settle's **transaction id** (`tid`), which is used to identify the payment in future API calls.
86+
87+
After creating the payment request, the vendor should poll the [`payment outcome`](https://developer.settle.eu/handlers.html#get--payment_request--tid--outcome- "GET /payment_request/\<tid>/outcome/") endpoint, and monitor status changes. A newly created payment request will have `status_code` set to _1003 (PENDING)_.
88+
89+
Example outcome with status _1003 (PENDING)_:
90+
91+
```json
92+
{
93+
"meta": {
94+
"seqno": 0,
95+
"labels": [
96+
97+
],
98+
"uri": null,
99+
"id": "D5S6WYjnQ_ObT-DyZfrVPA",
100+
"context": "ctx:D5S6WYjnQ_ObT-DyZfrVPA",
101+
"timestamp": "2019-03-21 08:58:49",
102+
"event": "shortlink_scanned"
103+
},
104+
"object": {
105+
"id": "token:5632006343884800",
106+
"argstring": "vendors_transaction_id"
107+
}
108+
}
109+
```
110+
111+
### 5. Payment confirmation
112+
113+
A message appears on the customer's phone asking them to confirm the payment.
114+
115+
If the user confirms the payment, the `status_code` returned from the [`payment outcome`](https://developer.settle.eu/handlers.html#get--payment_request--tid--outcome- "GET /payment_request/\<tid>/outcome/") endpoint changes to _3008 (AUTH)_:
116+
117+
```json
118+
// POST https://api.settle.demo/merchant/v1/payment_request/
119+
120+
{
121+
"action": "SALE",
122+
"allow_credit": true,
123+
"pos_tid": "vendors_transaction_id",
124+
"pos_id": "id-of-the-pos",
125+
"customer": "token:5632006343884800",
126+
"currency": "EUR",
127+
"amount": 2000
128+
}
129+
```
130+
131+
Note that `auth_amount` changed from `0` to `2000`.
132+
133+
If the user chooses to reject the payment, `status_code` changes to _5006 (REJECTED)_.
134+
135+
### 6. Waiting for authorization
136+
137+
As soon as the customer confirms the payment in their app, Settle will attempt to authorize the payment. When `status_code` changes to _3008 (AUTH)_, the payment can be captured.
138+
139+
### 7. Capturing the payment
140+
141+
The vendor captures the payment using the [`PUT /payment_request/<tid>/`](https://developer.settle.eu/handlers.html#put--payment_request--tid-- "PUT /payment_request/\<tid>/") endpoint, sending in `{action: "capture"}`:
142+
143+
```json
144+
{
145+
"id": "p2ybyw4tq73n",
146+
"uri": null
147+
}
148+
```
149+
150+
Note that the payment must be authorized before capture is possible; it is an error to try to capture a payment that does not have `status_code` _3008 (AUTH)_.
151+
152+
### 8. Verifying the capture
153+
154+
Again, polling the [`payment outcome`](https://developer.settle.eu/handlers.html#get--payment_request--tid--outcome- "GET /payment_request/\<tid>/outcome/"), the vendor can check the payment's `status_code` to see whether it succeeded. _2000 (OK)_ means that the payment is captured and has been transferred to the merchant:
155+
156+
```json
157+
// GET https://api.settle.demo/merchant/v1/payment_request/p2ybyw4tq73n/outcome/
158+
159+
{
160+
"status": "pending",
161+
"customer": "token:5632006343884800",
162+
"attachment_uri": <removed>,
163+
"pos_tid": "vendors_transaction_id",
164+
"refunds": [
165+
166+
],
167+
"auth_amount": 0,
168+
"auth_additional_amount": 0,
169+
"captures": [
170+
171+
],
172+
"date_modified": "2019-03-21 08:58:49",
173+
"date_expires": "2019-03-26 08:59:07",
174+
"credit": false,
175+
"amount": 2000,
176+
"interchange_fee": 0,
177+
"status_code": 1003,
178+
"tid": "p2ybyw4tq73n",
179+
"pos_id": "id-of-the-pos",
180+
"currency": "EUR",
181+
"additional_amount": 0,
182+
"transaction_fee": 0,
183+
"permissions": null
184+
}
185+
```
186+
187+
For a full list of status codes, see the [outcome documentation](https://developer.settle.eu/handlers.html#outcome).

‎toc.json‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -302,16 +302,6 @@
302302
"title": "Merchant API",
303303
"uri": "reference/merchant.v1.yaml"
304304
},
305-
{
306-
"type": "item",
307-
"title": "Short Dynamic Links API",
308-
"uri": "reference/Short-Dynamic-Links.yaml"
309-
},
310-
// {
311-
// "type": "item",
312-
// "title": "🔗 Short Dynamic Links API",
313-
// "uri": "docs/7. Reference Documentation/API's/short-dynamic-links-api.md"
314-
// },
315305
{
316306
"type": "group",
317307
"title": "Models",

0 commit comments

Comments
 (0)