Joyn - Public API Documentation
Documentation Powered by ReDoc

Joyn - Public API documentation (1.8.1)

Technical Support: api-integration@joyn.be URL: https://developer.joyn.be/v1 License: proprietary Terms of Service

Joyn Public API documentation

Introduction

This documentation describes how an external system or application can integrate with Joyn by using the Joyn public API. Via the API, developers or 3rd party integrators can access a number of extra services like giving away loyalty points.

FAQ

For whom is this documentation intended?

The purpose of this documentation is to provide technical information on how to integrate Joyn into an external application or system.
3rd parties like point-of-sale software providers (e.g. cash register systems) or e-commerce software builders (e.g. webshops) can integrate with the Joyn loyalty platform in several ways. Anyone who is familiar with RESTful, JSON APIs should have no problem getting started.

What kind of integrations does Joyn support?

The Joyn platform currently supports 2 types of integrations:

  • external applications linked to a Joyn shop (e.g. an online shop) can give away Joyn loyalty points via loyalty tokens. Joyn loyalty tokens are QR codes that a user can scan with the Joyn Android or iOS user app, thereby immediately receiving Joyn loyalty points for the shop that is linked to the token.

  • 3rd party point-of-sale applications are able to send the amount of a sale immediately to a Joyn merchant iPad located in a store and start a scan session. This is useful for not having to enter the amount of the sale twice on the POS and the iPad.

Is it possible to give away Joyn loyalty points on a webshop?

Yes. A webshop or any e-commerce system can use Joyn loyalty QR tokens to allow users to scan the tokens with the Joyn user app and immediately receive their loyalty points afterwards.
For example after an online purchase, a webshop can show a Joyn loyalty token at the end of the checkout process on the order confirmation page or in the order confirmation email.

However, a user collecting points should always be able to physically redeem the points at a shop, so the webshop must always be linked to an actual Joyn shop owning a Joyn merchant iPad.

I have a cash register system. How can I integrate it with Joyn?

There are several possibilities to set up an integration. For example, if a Joyn shop uses the 1 point per euro loyalty program, then the cashier probably doesn't want to enter the amount twice: first on the cash register system and secondly on the Joyn merchant iPad. Joyn offers the possibility to push the amount directly from the cash register system to the Joyn merchant iPad. This way, the amount of the sale mustn't be entered on the iPad again and your customer can immediately scan his card and receive his/her loyalty points.

Or, let's say a Joyn shop wants to offer its customers an alternative way of receiving loyalty points besides scanning on the Joyn merchant iPad right after a sale has been registered on the cash register system. By using Joyn loyalty tokens, an integrator is able to print loyalty QR codes on a receipt which a customer then can scan with the Joyn user app to collect his/her points.

Is there another way, besides calling the Joyn public API, to give away Joyn loyalty points?

Yes, there is! We've made it easier for 3rd parties or integrators to generate Joyn loyalty QR codes. You can create the QR codes completely client-side, which means you don't have to call the API. These codes are created based on a shared secret. You can read everything about it here. The client-side loyalty QR codes act in the same way as loyalty tokens that are generated via the API: a user can scan the QR code with the Joyn user app and collect his/her points.

Using the API

Endpoints

The API is located at https://api-v2.joyn.be (OAuth) and https://gateway.joyn.eu/api (API Key).

To use the API during development or testing, please use the staging version of the API located at our staging environment. The staging API is located at https://api-v2.acc.joyn.be and https://gateway.acc.joyn.eu/api.

All API requests should be made over HTTPS (‼️ Minimum TLS Version is 1.2).

Testing

In case of requesting a Joyn loyalty token, you probably want to test out scanning the QR code with the Joyn user app. In case of sending an amount to the Joyn merchant app running on an iPad, you probably want to test the functionality and see the scan session appearing on the Joyn merchant app. We can therefore send you a version of the Joyn user app (iOS or Android) or the Joyn merchant iPad app (iOS) that connects to the staging environment.
Please contact our Technical help center to help you with that.

Once we have validated that all functionality is according to our guidelines, we will give your application access to our production environment.

Support

If something would be unclear or if you have a question or need any technical assistance, you can contact our technical help center via api-integration@joyn.be.

Authentication

Depending on the api, authentication can be done via the OAuth 2.0 protocol or an api key.

Api Key

There are two types of API key.

Type PARTNER : this API key can be obtained by partners by contacting Joyn (see the Technical support section).

Type SHOP : This API Key can be obtained in the merchant portal by the merchant himself for some integrations like WooCommerce. For some integrations the partner must contact Joyn.

The API key should be passed in the Authorization header. The format of the header value is the scheme ApiKey followed by the actual API Key

Authorization : ApiKey d87bf4f0-693e-4702-97de-c6d3d838b00f

Security Scheme Type API Key
Header parameter name: Authorization

OAuth2

OAuth2 is a protocol that lets external apps request authorization to do API calls on a user’s behalf without getting their password. This allows tokens to be limited to specific permissions, and can be revoked by users at any time. It's an open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

You’ll need an access token to be able to communicate with the Joyn API. The token holds the credential that allows you to access the API.

To obtain an access token, you must use the OAuth 2.0 Client Credentials flow. This flow is mainly used for inter-service data access, and may only to be used between trusted parties.

The access token needs to be formatted as a JSON Web Token (JWT) and passed in requests to the API in the HTTP Authorization header.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://api.joyn.be/oauth/token
Scopes:
  • service -

    3rd party service

OAuth2 Token

The required parameters depend on the grant type requested

header Parameters
Authorization
required
any

A base64-encoded client_id:client_secret string used for authentication

Responses

200

Success

post/oauth/token

Staging URL

https://api.acc.joyn.be/oauth/token

Production URL

https://api.joyn.be/oauth/token

Request samples

Copy
curl -X POST 
-H 'Authorization: Basic {base64_encoded_client}' 
-d "grant_type=client_credentials" 
"https://api.acc.joyn.be/oauth/token"

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expires_in": 2592000,
  • "jti": "54b8ed0f-b7d6-4a52-929d-e3f80fa7b98c",
  • "refresh_token": "82d82cf4-76gf-gfds-nt3k-lzpo12jg",
  • "scope": "service",
  • "token_type": "bearer"
}

Automatic Loyalty

The automatic loyalty API allows a third party to hand out loyalty points to a customer of a shop based on the payment done. The third party must be able to identify the customer using a Joyn qrcode. Together with the shopReference and payment amount the identified customer will receive points depending on the shop’s loyalty program.

Register payment and give loyalty

This api registers a payment done on the partners device and hands out loyalty based on the provided information

header Parameters
Authorization
required
string

ApiKey scheme followed by valid API Key

Authorization : ApiKey d87bf4f0-693e-4702-97de-c6d3d838b00f

Request Body schema: application/json

Request to retrieve a loyalty token

amount
required
number

Payment amount in cents.

currency
required
string

Payment currency code in ISO 4217 format.

paymentReference
required
string

Unique reference that identifies the payment. MUST be unique for all requests for the same partner.

shopReference
required
string

A reference that identifies the shop. It’s not yet possible to obtain a shop reference for a Joyn shop automatically. A partner can request this reference manually (see the Technical support section) by providing the name and location (address, city) of the shop. This shop must have a Joyn contract, otherwise the request will be denied.

userIdentifier
required
string

The customer's qrcode. Can be the qrcode of a physical card or the user app.

Responses

200

OK

400

Bad Request

401

Unauthorized

post/api/loyalty

Staging URL

https://gateway.acc.joyn.eu/api/loyalty/api/loyalty

Production URL

https://gateway.joyn.eu/api/loyalty/api/loyalty

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 1580,
  • "currency": "EUR",
  • "paymentReference": "1234",
  • "shopReference": "A8B81BC5-4A06-1146-B88A-11B38B644EBA",
  • "userIdentifier": "6DEBD6984F6CA7FF2182C5610809E5B293C4E40E461C7A18AC96BA58C195174A"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "balance": 79,
  • "earned": 16
}

Loyalty Token

A Joyn loyalty token contains a URL that can be used to give away Joyn loyalty points for a specific Joyn merchant. In order to collect the points a user must have the Joyn Android or iOS user app installed.
An integrator could choose to visualize the token as a QR code which can then be scanned by a user with the Joyn app, thereby immediately receiving loyalty points for the shop that is linked to the token.
Or the integrator can choose to put the URL behind a clickable button on a mobile device.

In the latter case, it is important to note that the Joyn loyalty token URL's are also deeplinked to the Joyn user app, meaning that the Joyn user app is automatically opened and activated when being redirected to the token URL on a mobile device. If the Joyn user app is not installed on a mobile device, then the token URL will redirect to a download page for the Joyn user app.
In both scenarios (scanning a token QR code or clicking on a token URL on a mobile device), the user will immediately receive his/her loyalty points in the Joyn user app after having successfully performed the call-to-action.

Request a Joyn loyalty token using an API Key

Creates and returns a Joyn loyalty token for a certain Joyn shop. A Joyn loyalty token is mostly visualized in the form of a QR code. These tokens can be redeemed by a user using the Joyn user app, resulting in the user earning Joyn loyalty points of that shop. The Joyn shop is identified by the API Key used.

header Parameters
Authorization
required
string

ApiKey scheme followed by valid API Key

Authorization : ApiKey d87bf4f0-693e-4702-97de-c6d3d838b00f

Request Body schema: application/json

Request to retrieve a loyalty token using an API key

amount
required
number

Transaction amount in EUR. This field is only required in case the Joyn shop hands out loyalty points according to the 1 point per 1 EUR loyalty program. In this case, the loyalty token will hold the number of points corresponding to this program (e.g. 10 EUR = 10 points, 11.60 EUR = 12 points).
If the field is omitted, then the number of points will be set to 5 by default.

partnerReference
string

The partner reference linked to a Joyn shop. Only needed if the supplied api key is of type PARTNER. This reference is unique to the integrating partner.
It’s not yet possible to obtain a partner reference for a Joyn shop automatically. A partner can request this reference manually (see the Technical support section) by providing the name and location (address, city) of the shop. The shop must have a Joyn contract, otherwise the request will be denied.

transactionReference
string

A unique transaction reference to store with the loyalty token

Responses

201

Created

400

Bad Request

401

Unauthorized

post/api/tokens

Staging URL API Key

https://gateway.acc.joyn.eu/api/tokens

Production URL API Key

https://gateway.joyn.eu/api/tokens

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 15.8,
  • "partnerReference": "B429AB7D-4441-4673-AB56-32F61D36823A",
  • "transactionReference": "trx-ref-abc"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Request a Joyn loyalty token

Creates and returns a Joyn loyalty token for a certain Joyn shop. A Joyn loyalty token is mostly visualized in the form of a QR code. These tokens can be redeemed by a user using the Joyn user app, resulting in the user earning Joyn loyalty points of that shop. The Joyn shop is identified by a partner reference.

Authorizations:
OAuth2
Request Body schema: application/json

Request to retrieve a loyalty token

amount
number

Transaction amount in EUR. This field is only required in case the Joyn shop hands out loyalty points according to the 1 point per 1 EUR loyalty program. In this case, the loyalty token will hold the number of points corresponding to this program (e.g. 10 EUR = 10 points, 11.60 EUR = 12 points).
If the field is omitted, then the number of points will be set to 5 by default.

partnerReference
required
string

The partner reference linked to a Joyn shop. This reference is unique to the integrating partner.
It’s not yet possible to obtain a partner reference for a Joyn shop automatically. A partner can request this reference manually (see the Technical support section) by providing the name and location (address, city) of the shop. The shop must have a Joyn contract, otherwise the request will be denied.

transactionReference
required
string

A unique transaction reference to store with the loyalty token

transactionTimestamp
string

Optional transaction timestamp. If empty, the current date will be used.

Responses

201

Created

400

Bad Request

401

Unauthorized

409

Conflict

post/partner/tokens

Staging URL

https://api-v2.acc.joyn.be/api/v2/partner/tokens

Production URL

https://api-v2.joyn.be/api/v2/partner/tokens

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 15.8,
  • "partnerReference": "40E6345D-0272-4E7F-BC8D-E577F9D77A68",
  • "transactionReference": "trx-ref-abc",
  • "transactionTimestamp": "2018-09-24T14:10:55.000Z"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 15.8,
  • "badge": "<html><img src=\"https://chart.googleapis.com/chart?cht=qr&code=https://joyn.be?code=token\"/></html>",
  • "createdDate": "2018-09-25T14:09:30.221+02:00",
  • "expirationDate": "2018-10-01T14:09:30.221+02:00",
  • "lastModifiedDate": "2018-09-25T14:21:13.658+02:00",
  • "points": 16,
  • "qrCodeUrl": "https://chart.googleapis.com/chart?cht=...",
  • "shopName": "La Parisienne (French Bakery)",
  • "source": "third-party",
  • "status": "CREATED",
  • "token": "fddabb5c-868b-41d5-90e3-a4d2ddfd98a7",
  • "tokenUrl": "http://joyn.be?code=token",
  • "transactionReference": "trx-ref-abc",
  • "transactionTimestamp": "2018-09-24T14:10:55.000Z",
  • "validityPeriod": "P1D"
}

Retrieve an existing Joyn loyalty token

Retrieves detailed information about an existing Joyn loyalty token

Authorizations:
OAuth2
path Parameters
token
required
string

The token for which the information should be retrieved

Responses

200

OK

401

Unauthorized

404

Not Found

get/partner/tokens/{token}

Staging URL

https://api-v2.acc.joyn.be/api/v2/partner/tokens/{token}

Production URL

https://api-v2.joyn.be/api/v2/partner/tokens/{token}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount": 15.8,
  • "badge": "<html><img src=\"https://chart.googleapis.com/chart?cht=qr&code=https://joyn.be?code=token\"/></html>",
  • "createdDate": "2018-09-25T14:09:30.221+02:00",
  • "expirationDate": "2018-10-01T14:09:30.221+02:00",
  • "lastModifiedDate": "2018-09-25T14:21:13.658+02:00",
  • "points": 16,
  • "qrCodeUrl": "https://chart.googleapis.com/chart?cht=...",
  • "shopName": "La Parisienne (French Bakery)",
  • "source": "third-party",
  • "status": "CREATED",
  • "token": "fddabb5c-868b-41d5-90e3-a4d2ddfd98a7",
  • "tokenUrl": "http://joyn.be?code=token",
  • "transactionReference": "trx-ref-abc",
  • "transactionTimestamp": "2018-09-24T14:10:55.000Z",
  • "validityPeriod": "P1D"
}

Client-side Loyalty QR code

The Joyn platform also supports creating loyalty token QR codes without actually calling the Joyn public API every time you want to generate a QR token. We call these client-side QR codes since there's no need to communicate with the Joyn server.

To do this, a partner or integrator must obtain 3 key elements before being able to create the QR code: a partner key , a shop reference and a shared secret. To request these elements, please contact our Technical Support team via api-integration@joyn.be. Once obtained, the partner will be able to build the QR token URL according to the following format:

https://scan.joyn.be/l/{partnerKey}/?{shopReference}&{receiptId}&{amount}&{timestamp}&{hash}

The table below describes the parameters that are used in the URL:

Parameter Description Example
partnerKey This key string identifies the 3rd party that has created the loyalty QR code. partnerXYZ
shopReference A reference that uniquely identifies the Joyn shop for which the QR code is created dpSvh575V1
receiptId A unique identifier of the 3rd party transaction. Points are handed out only once for every receipt ID. ticket1234
amount The amount (in euros) of the transaction. Depending on the loyalty program of the shop, points are calculated based on this amount. A point is used as the decimal symbol. 6.40
timestamp The time when the QR token was created. This must be a Unix time number. By default, a loyalty QR code expires after 2 hours. This can be increased on request. 1538643511
hash A SHA-1 hash based on a shared secret which proves the QR code was created by the party that owns the shared secret. 4361e12455a8f081f6a28ea21babb6b8557d9a4d

Step-by-step guide to build a client-side Joyn loyalty QR code:

  1. Construct the URL by replacing all parameters and using the shared secret that you obtained from Joyn at the end of the URL: 

    https://scan.joyn.be/l/partnerXYZ/?dpSvh575V1&ticket1234&6.40&1538643511&{sharedSecret}

  2. Calculate the SHA-1 hash of this URL:

    D6F838D2F555728DF32F27408052988783EE0E98

    The SHA-1 algorithm has implementations in almost every programming language. A list of cryptography libraries that support SHA-1 can be found on the SHA-1 Wikipedia page

  3. Replace the secret with the hash in the URL of step 1: 

    https://scan.joyn.be/l/partnerXYZ/?dpSvh575V1&ticket1234&6.40&1538643511&D6F838D2F555728DF32F27408052988783EE0E98

  4. Create a QR code with this string: 

    https://chart.googleapis.com/chart?cht=qr&chs=260x260&chl=https://scan.joyn.be/l/partnerXYZ/?dpSvh575V1%26ticket1234%266.40%261538643511%26D6F838D2F555728DF32F27408052988783EE0E98

QR codes that are generated this way can be scanned with the Joyn Android or iOS user app. These QR codes can be published anywhere: for example on a receipt, on a web page or in an email.
After a user successfully scans such a QR code with the Joyn user app, the user instantly receives loyalty points from the shop that is referenced in the QR code based on the loyalty program of the shop. By default, a Joyn loyalty QR token expires 2 hours after being created. Once a user has successfully scanned a QR token, the token becomes invalid and can't be scanned anymore.

Scan Session

A scan session tells the Joyn merchant iPad to show the scan screen and invites a customer to scan his Joyn loyalty card and collect points.

Start a scan session

This method is used to start a scan session on the Joyn merchant iPad without the merchant having to enter the sale amount on the iPad manually. The merchant iPad is identified by a unique POS ID.
A cash register for example can use this method to pass the amount of a sale to the Joyn merchant iPad after which a customer is able to immediately scan his Joyn loyalty card on the iPad and receive loyalty points in the store.

Authorizations:
OAuth2
path Parameters
shopPartnerReference
required
string

The shop reference identifying the Joyn shop for which the scan session is triggered. This reference should be requested and is not the shopId. It is different for each integration partner.

It’s not yet possible to obtain a partner reference for a Joyn shop automatically. A partner can request this reference manually (see the Technical support section) by providing the name and location (address, city) of the shop. This shop must have a Joyn contract, otherwise the request will be denied.

posUniqueId
required
string

The ID identifying the Joyn POS (e.g. a cash register system) that a Joyn merchant app is subscribed to. A Joyn merchant must first have configured his Joyn merchant app to correspond to a POS. This will link the Joyn merchant app to a unique ID, i.e. the Joyn POS ID.

Currently a Joyn POS can only be created and activated by the Joyn technical operations team on behalf of a Joyn merchant. Once activated, it’s up to the merchant to link his Joyn merchant iPad with the corresponding POS via the merchant app settings. To obtain the correct Joyn POS ID, ask the merchant to provide the ID or contact our Technical support team for more information.

Request Body schema: application/json
currency
required
string

The currency in which totalAmount and outstandingAmount are passed. This must be a valid ISO 4217 currency code. For now, this value should always be 'EUR'.

outstandingAmount
number

This is the optional total outstanding amount in cents of the transaction that still needs to be paid. This value must be formatted in the smallest precision of the given currency. Example: if a transaction has an outstanding amount of €30,00, this value should contain the value 3000.

totalAmount
required
number

This is the total amount of the transaction in cents. This value must be formatted in the smallest precision of the given currency. Example: if a transaction of €30,00 is made, this value should contain the value 3000. If the transaction amount is €0,50, the value should be 50.

transactionId
required
string

A transaction identifier / reference generated by the cash register.

Responses

202

Accepted

400

Bad Request

401

Unauthorized

404

Not Found

post/shops/{shopPartnerReference}/pos/{posUniqueId}/scan-session

Staging URL

https://api-v2.acc.joyn.be/api/v2/shops/{shopPartnerReference}/pos/{posUniqueId}/scan-session

Production URL

https://api-v2.joyn.be/api/v2/shops/{shopPartnerReference}/pos/{posUniqueId}/scan-session

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency": "EUR",
  • "outstandingAmount": 500,
  • "totalAmount": 800,
  • "transactionId": "your-transaction-ID"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "errorMessage": "Validation error",
  • "fieldErrors":
    [
    ],
  • "statusCode": "400"
}