# Suriwallet API - integration
This documentation is for integrating the Suriwallet API and features into your Kiosk, POS, App, webshop, or other solutions.

All request types and models can be found here: https://suriwallet-api.stampwallet.io/docs/

The information below will get you started. The information on our API page will give you access to all available requests.

## API credentials
* You need a Suriwallet account first
* Sign in to your account on https://suriwallet.web.app/
* On the top right you see your email address, click on it.
* Now click on 'settings'
* You will now receive 2 important credentials:
* A Token: `4afb9200-f2eb-11ec-abcc-3b71b2fd60b1`
* Your PlaceID: `-N5FPZYtCkgXVKgQOdmy`
* You need both to fetch or write data from or to the API

## GET promotions
The first step is to retrieve a PromotionID, this is needed to give stamps, refill credits, redeem rewards, redeem coupons, and to receive credits from users.

### Request

curl -v \
	-X GET \
	-H "Authorization: 4afb9200-f2eb-11ec-abcc-3b71b2fd60b1" \
	-H "Content-Type: application/json" \
	"https://suriwallet-api.stampwallet.io/places/-N5FPZYtCkgXVKgQOdmy/promotions"

* The Authorization header is the token you retrieved from your account ([check API credentials](https://hackmd.io/KE9TpkucRiKTUTjYvx1TeQ#API-credentials))
* The token in the URL after **/places/** is your **placeID**.

### Response
You will receive the following response:

[
  {
    "id": "-N5GKRAJuXzK4JwWn0SO",
    "currency": {
      "code": "SRD",
      "id": "-Kdfd6hAHuSD1E80X8oD",
      "name": "Suriname Dollar",
      "symbol": "SRD"
    },
    "endDate": 1661396340000,
    "longDescription": "Spend SRD 100.- in one of our restaurants and earn a stamp. \n10 stamps give you a discount of 10% discount on all family meals.",
    "placeId": "-N5FPZYtCkgXVKgQOdmy",
    "shortDescription": "10% discount",
    "startDate": 1656000600000,
    "title": "10% discount on all family meals!",
    "type": "stamps",
    "maxStamps": 1,
    "stampPrice": 10,
    "stamps": 10
  }
]

The ID is most important, you will need this to create transactions. The other info can be used to display information and to check the **stampPrice**. The **stampPrice** is important, because this will calculate how many stamps the customer will receive after a transaction total. For example:
> The stampPrice is 10, when you create a transacation with a amount is 100, this will create 10 stamps.

## Create a unique QR code with a stamp value.
You can now create a unique QR code. This QR code will hold an amount of stamps based on the stampPrice. The QR-code can be scanned by users of the Suriwallet app. They will receive the stamps on the promotion (loyalty card) you used to create his QR code.

## Request

curl -v \
	-X POST \
	-H "Authorization: 4afb9200-f2eb-11ec-abcc-3b71b2fd60b1" \
	-H "Content-Type: application/json" \
	-d "{
  \"token\": \"-N5GKRAJuXzK4JwWn0SO\",
  \"price\": 10,
  \"image\": true
}" \
	"https://suriwallet-api.stampwallet.io/qr/unique"

* Authorization: your token
* Token: the placeID token
* Price: amount of purchase
* Image:
* **True:** generates a QR code image (svg) you can use to print on a receipt or show on a display.
* **False:** generates a link, which you can use to generate your own QR code (or use it on your website in checkout)

## Create a transacation based on userID
In scenario's where your user accounts are connected to suriwallet account, you can retrieve the userID of your follower. For testing, go to your account in our dashboard. Go to followers. Click on a user, and you will see a unique ID in the url of the page. for example:`https://suriwallet.web.app/users/jMVuvdeMTlgA5KNgGuMi91997Kn2`

In this case `jMVuvdeMTlgA5KNgGuMi91997Kn2` is the userID.

You can now create a transaction for this specific user.

### Request

curl -v \
	-X POST \
	-H "Authorization: 4afb9200-f2eb-11ec-abcc-3b71b2fd60b1" \
	-H "Content-Type: application/json" \
	-d "{  
   \"user_id\":\"jMVuvdeMTlgA5KNgGuMi91997Kn2\",
   \"promotion_id\":\"-N5GKRAJuXzK4JwWn0SO\",
   \"amount\":1,
   \"action\":\"server\"
}" \
	"https://suriwallet-api.stampwallet.io/places/-N5FPZYtCkgXVKgQOdmy/transactions"

* Authorization: your token
* User_id: the userID token
* Promotion_id: the ID of the promotion you want to use
* Amount: 1 (the amount of stamps, you need to calculate this yourself, because it's also possible to give stamps based on a visit, line-item, etc)
* Action: server (needed for this flow)

> **IMPORTANT:** in this case, you need to calculate the amount of stamps yourself. This is due to the fact, that you can also give stamps based on visits or line-items / products. For example you buy 1 burger and you get 1 stamp. This is a deeper integration and therefore you need full flexibility.