Introduction

The documentation describes business processes and REST API methods provided by the Payment link service. The API allows you to easily and safely automate the process of creating a partner’s payment link.

API can be used for:

creating a partner’s payment link

How to start?

To integrate with the Conotoxia Payment link system, the Partner needs:

API client identifier and API client secret needed to obtain an access token to Conotoxia API.
Identifier of their public key (kid) added to Conotoxia Payment link system.
Conotoxia host addresses which are described in the following documentation: CONOTOXIA_OIDC_HOST and CONOTOXIA_HOST.
The Partner should have a store configured with a point of sale

Creation of a payment link

To create a payment link, simply follow a few easy steps:

Generate the access token using the POST /connect/token resource. This token should be placed in the Authorization header when communicating with all resources of the Conotoxia API.
With your own private key, you must sign the request body (an example of the request can be found in the chapter Creating a payment link). JWS, which will be sent to Conotoxia API, should have public key identifier (kid) in header section. It will be used to verify requests by the Conotoxia system.
Execute request on the POST /v1/links resource by placing in the request body JWS data and setting the correct header according to the information provided in the Communication with Conotoxia section.
The received response should be decoded and verified in accordance with the information provided in the Communication with Partner section.
The response contains the address to which the customer should be redirected in order to approve the payment.

Authorization

To use Conotoxia, it is necessary to process authentication. Each API request provided by Conotoxia requires sending an Authorization header containing an access token, the so-called OAuth 2.0 access token. In order to generate the token, use the POST /connect/token resource. Authentication is performed using HTTP Basic, where the user name is api_client_secret and the password is api_client_secret. In the request's body, specify the grant_type parameter set to client_credentials and the scope parameter with the pay_api value.

Generating access token

POST <CONOTOXIA_OIDC_HOST>/connect/token

Example Request

curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -u "<api_client_id>:<api_client_secret>" \
     -d "grant_type=client_credentials&scope=pay_api" \
     "<CONOTOXIA_OIDC_HOST>/connect/token"

Example Response

{
  "access_token": "M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM",
  "expires_in": 900,
  "token_type": "Bearer"
}

The REST API method for obtaining an access token.

Resource

POST <CONOTOXIA_OIDC_HOST>/connect/token

Request headers

Name	Value	Remarks
Authorization	Basic <credentials>	HTTP Basic Authentication. <credentials> is the Base64 encoding of ID and password joined by a single colon. e.g: Basic api_client_id:api_client_secret
Content-Type	application/x-www-form-urlencoded

Request body

Parameters according to client_credentials mode

Name	Value	Description
grant_type	client_credentials	HTTP Basic Authentication.
scope-Type	pay_api

Response

Field name	Type	Required	Description
access_token	string	YES	Token, which must be indicated when using the API provided by Conotoxia.
expires_in	string	YES	Token validity time in seconds.
token_type	string	YES	Token type.

Payment links

Create a link

Resource

POST <CONOTOXIA_HOST>/v1/links

Example Request

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en" \
     "<CONOTOXIA_HOST>/v1/links" \
     -d "@data.json"

data.json
     {
        "name": "Example of payment link",
        "pointOfSaleId": "POS1877542915625404",
        "amount": {
          "currency": "EUR",
          "value": 100
        },
        "validTo": "2030-05-11T12:00:00.0Z",
        "message": "Payment for guitar",
        "notificationUrl": "http://host/notifications/receive",
        "notificationUrlParameters": {
          "exampleKey": "exampleValue"
        }
     }

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     "<CONOTOXIA_HOST>/v1/links" \
     -d "@data.jws"

data.jws
     eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJuYW1lIjogIkV4YW1wbGUgb2YgcGF5bWVudCBsaW5rIiwKICAicG9pbnRPZlNhbGVJZCI6ICJQT1MxODc3NTQyOTE1NjI1NDA0IiwKICAiYW1vdW50IjogewogICAgImN1cnJlbmN5IjogIkVVUiIsCiAgICAidmFsdWUiOiAxMDAKICB9LAogICJ2YWxpZFRvIjogIjIwMzAtMDUtMTFUMTI6MDA6MDAuMFoiLAogICJtZXNzYWdlIjogIlBheW1lbnQgZm9yIGd1aXRhciIsCiAgIm5vdGlmaWNhdGlvblVybCI6ICJodHRwOi8vaG9zdC9ub3RpZmljYXRpb25zL3JlY2VpdmUiLAogICJub3RpZmljYXRpb25VcmxQYXJhbWV0ZXJzIjogewogICAgImV4YW1wbGVLZXkiOiAiZXhhbXBsZVZhbHVlIgogIH0KfQo.C4lzvgzkKyPEJ6khviZ9mCG1QZW8ikoWgmIaFAsqxwZQAKAZI1RDQABFQYZczUrz0CyJVXu4EeOPNdF1IZs-z1PyyNa1QtozFtc6IzD6TYIEqThv3wgLyquR14sdBHP3OJiOT18-PAkGFXj2siZ5SyitGRkivJGg7toZg_f2E0DLApQZHMtWrvp1wwxHro-VMA6K_aYEK79VtrVxP7raOqjzytzOqkHETeZ499o-WxmpEh__oJZNLsDgryf9C-S3s5FBoV9JInxzLC_gEdQ136qNzvSWPecJnvFzDyudacg8iv9fvw3aZGNohsUGodkAN022-k7stxtdanfblDwQ1w

Response headers:

HTTP/1.1 201 Created
Content-Type: application/json

HTTP/1.1 201 Created
Content-Type: application/jose+json

Example Response

{
  "publicId": "PLK2669259288350020",
  "url": "https://<CONOTOXIA-LINK-HOST>/TOhIak0TTi"
}

    eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJwdWJsaWNJZCI6ICJQTEsyNjY5MjU5Mjg4MzUwMDIwIiwKICAidXJsIjogImh0dHBzOi8vPENPTk9UT1hJQS1MSU5LLUhPU1Q-L1RPaElhazBUVGkiCn0K.qCS94aff1p95aU9tX4i0w2b4S1YUPnZyF_XRrjmWAxgms3cu1rfoWYBcjUnARQB3HOKRvI1G3Z8iO-INLBjAZ9kiLSjVIyYe_X5-1ksyyL2Rq5i6JZj8xGUB3U1D_cxHjt-B-hA81UsnVn2fRzsKsiYlGglJtaaGn6uc8KxSOiHuf8L0H4_tgZbHc51rk5LWRnQU3l5QiDuLGi5I5HHh4-_7BWBJWPLZHGYNaNj85hRHok-KvQ3vrlYxo1b1ZXb--lMP8MgpDn_SdrNOCh_hOi6dhq5T7QuvVNFDuiPy6PZUHmuMXQrrFGTVKjVlvY1Lu2TcnOciZourdkNrbi5FFQ

The REST API method allows you to create payment link.

Resource

POST <CONOTOXIA_HOST>/v1/links

Request headers

Name	Value	Description
Authorization	Bearer <access_token>	Access token to authorize request. Described in the Authorization chapter.
Content-Type	application/jose+json	Format of request body data.
Accept-Language	<language>	A header that sets one of the two payment interface domains. For pl, it is `<CINKCIARZ_PAY_WEB_HOST>`, and for other languages (or no header setting), it is `<CONOTOXIA_PAY_WEB_HOST>`. It must comply with the RFC 7231 specification.

Request body

Field name	Type	Required	Description
name	text	YES	The payment link name. The Length: 1 - 75 characters
pointOfSaleId	text	YES	Point of sale identifier. Length: 18 - 50 characters
amount	json	YES	Payment amount with the currency.
amount.currency	text	YES	Define payment currency. Currency uppercase ISO 4217 code. Supported currency codes are described in Currencies dictionary.
amount.value	number	YES	Define the payment amount. Max. 21 characters with support for 4 places after the decimal separator (a dot (.) is used as the decimal separator). The number of places after the decimal separator depends on the currency and is given in the Currencies dictionary.
validTo	datetime	NO	Date and time (according to ISO 8601 format YYYY-MM-ddTHH:mm:ss.fffZ) which sets the expiration date of the payment link.
message	text	NO	Message for a payer. Max. 255 characters
notificationUrl	text	NO	A URL to which payment status notifications will be sent. As a default, the URL provided by the Partner in the configuration of the point of sale is used. Length: 1 - 2048 characters
notificationUrlParameters	object	NO	Additional parameters, which are sent in URL payment status notifications. Max. 1024 characters

Response headers

Name	Value	Description
HTTP/1.1	201	Response status.
Content-Type	application/json	Response content type.

Response body

Field name	Type	Description
publicId	text	Payment link public identifier.
url	text	The payment link URL.

Dictionaries

List of supported currencies

No.	Currency	Currency code	Fraction digits	Minimum currency units for a transaction
1.	Dirham (United Arab Emirates dirham/Emirati dirham)	AED	2	1
2.	Australian dollar	AUD	2	1
3.	Bulgarian lev	BGN	2	1
4.	Canadian dollar	CAD	2	1
5.	Swiss franc	CHF	2	1
6.	Chinese yuan, Renminbi	CNY	2	1
7.	Czech koruna	CZK	2	10
8.	Danish krone	DKK	2	10
9.	Euro	EUR	2	1
10.	British pound	GBP	2	1
11.	Hong Kong dollar	HKD	2	1
12.	Hungarian forint	HUF	0	100
13.	Israeli new shekel	ILS	2	1
14.	Japanese yen	JPY	0	100
15.	Mexican peso	MXN	2	1
16.	Norwegian krone	NOK	2	10
17.	New Zealand dollar	NZD	2	1
18.	Polish zloty	PLN	2	1
19.	Romanian leu	RON	2	1
20.	Serbian dinar	RSD	2	10
21.	Swedish krone	SEK	2	10
22.	Singapore dollar	SGD	2	1
23.	Thai baht	THB	2	100
24.	Turkish lira	TRY	2	1
25.	United States dollar	USD	2	1
26.	South Africa rand	ZAR	2	1

Security

The Conotoxia Payment link system uses the following elements which ensure the security of communication with the Partner's system:

all communication takes place with the use of HTTPS protocol;
it is required to send an authorization token in the Authorization header in order to use the API (more information in the Authentication section);
all messages sent from the Partner's system must be signed (more information in the Communication with Conotoxia section);
all messages sent from the Conotoxia system are signed (more information in the Communication with the Partner section);
additional data that are attached to the URL parameters are signed by Conotoxia when redirecting to the Partner's website (more information in the chapter Authenticity of URL parameters).

Message authenticity

The JSON Web Signature specification defines how messages can be signed. JWS is encoded using base64url and consists of three parts separated by dots (.). The structure of JWS is as follows:

base64url(utf8(header)).base64url(payload).base64url(signature)

Example of a minimum JWS header accepted by Conotoxia:

{
  "alg": "RS256",
  "kid": "iQn7M-Eyzw5sde5GwaOu51Xzl8WFXJzNW3pmCBENhhk"
}

The first part is a header, which contains, among other things, information about the algorithm used to calculate the signature - the parameter "alg". The possible values which can be taken by the parameter "alg" are given in the table below:

Identifier	Algorithm
RS256	SHA256withRSA
RS384	SHA384withRSA
RS512	SHA512withRSA

The minimal JWS header, in addition to the parameter "alg", must also contain the parameter "kid", identifying the public key used to verify the signature.

Payload

The second part of JWS is the so-called payload, which contains the message being sent. JWS specification does not define the type of message that is sent (it can be, e.g. XML or String), but Conotoxia requires that the message be sent in JSON format (UTF-8 encoding).

Signature

The third part of JWS is a digital signature, calculated using the algorithm given in the JWS header for a combined coded header and coded message, separated by a dot (.).

Communication with Conotoxia

JWS Header

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "application/json",
  "kid": "8HdTeGmlqFQEoH1PsvY5E3QuPN0mr5JJ97eR6gSm6iU"
}

JWS Payload

{
  "name": "Example of payment link",
  "pointOfSaleId": "POS1877542915625404",
  "amount": {
    "currency": "EUR",
    "value": 100
  },
  "validTo": "2030-05-11T12:00:00.0Z",
  "message": "Payment for guitar",
  "notificationUrl": "http://host/notifications/receive",
  "notificationUrlParameters": {
    "exampleKey": "exampleValue"
  }
}

Example of a create payment link:

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/jose+json" \
     -d "@data.jws" \
     "<CONOTOXIA_HOST>/v1/links"

data.jws
     eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJuYW1lIjogIkV4YW1wbGUgb2YgcGF5bWVudCBsaW5rIiwKICAicG9pbnRPZlNhbGVJZCI6ICJQT1MxODc3NTQyOTE1NjI1NDA0IiwKICAiYW1vdW50IjogewogICAgImN1cnJlbmN5IjogIkVVUiIsCiAgICAidmFsdWUiOiAxMDAKICB9LAogICJ2YWxpZFRvIjogIjIwMzAtMDUtMTFUMTI6MDA6MDAuMFoiLAogICJtZXNzYWdlIjogIlBheW1lbnQgZm9yIGd1aXRhciIsCiAgIm5vdGlmaWNhdGlvblVybCI6ICJodHRwOi8vaG9zdC9ub3RpZmljYXRpb25zL3JlY2VpdmUiLAogICJub3RpZmljYXRpb25VcmxQYXJhbWV0ZXJzIjogewogICAgImV4YW1wbGVLZXkiOiAiZXhhbXBsZVZhbHVlIgogIH0KfQo.C4lzvgzkKyPEJ6khviZ9mCG1QZW8ikoWgmIaFAsqxwZQAKAZI1RDQABFQYZczUrz0CyJVXu4EeOPNdF1IZs-z1PyyNa1QtozFtc6IzD6TYIEqThv3wgLyquR14sdBHP3OJiOT18-PAkGFXj2siZ5SyitGRkivJGg7toZg_f2E0DLApQZHMtWrvp1wwxHro-VMA6K_aYEK79VtrVxP7raOqjzytzOqkHETeZ499o-WxmpEh__oJZNLsDgryf9C-S3s5FBoV9JInxzLC_gEdQ136qNzvSWPecJnvFzDyudacg8iv9fvw3aZGNohsUGodkAN022-k7stxtdanfblDwQ1w

curl -X POST \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en" \
     "<CONOTOXIA_HOST>/v1/links" \
     -d "@data.json"

data.json
     {
        "name": "Example of payment link",
        "pointOfSaleId": "POS1877542915625404",
        "amount": {
          "currency": "EUR",
          "value": 100
        },
        "validTo": "2030-05-11T12:00:00.0Z",
        "message": "Payment for guitar",
        "notificationUrl": "http://host/notifications/receive",
        "notificationUrlParameters": {
          "exampleKey": "exampleValue"
        }
     }

Response headers:

HTTP/1.1 201 Created
Content-Type: application/json

HTTP/1.1 201 Created
Content-Type: application/jose+json

Example Response

{
  "publicId": "PLK2669259288350020",
  "url": "https://<CONOTOXIA-LINK-HOST>/TOhIak0TTi"
}

    eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJwdWJsaWNJZCI6ICJQTEsyNjY5MjU5Mjg4MzUwMDIwIiwKICAidXJsIjogImh0dHBzOi8vPENPTk9UT1hJQS1MSU5LLUhPU1Q-L1RPaElhazBUVGkiCn0K.qCS94aff1p95aU9tX4i0w2b4S1YUPnZyF_XRrjmWAxgms3cu1rfoWYBcjUnARQB3HOKRvI1G3Z8iO-INLBjAZ9kiLSjVIyYe_X5-1ksyyL2Rq5i6JZj8xGUB3U1D_cxHjt-B-hA81UsnVn2fRzsKsiYlGglJtaaGn6uc8KxSOiHuf8L0H4_tgZbHc51rk5LWRnQU3l5QiDuLGi5I5HHh4-_7BWBJWPLZHGYNaNj85hRHok-KvQ3vrlYxo1b1ZXb--lMP8MgpDn_SdrNOCh_hOi6dhq5T7QuvVNFDuiPy6PZUHmuMXQrrFGTVKjVlvY1Lu2TcnOciZourdkNrbi5FFQ

All messages sent from the Partner's system to the Conotoxia Payment Link system must be sent in JWS format. Only in case of adding a public key it is not necessary to sign the message.

Below is an example of JWS (Compact Serialized), which can be sent to Conotoxia:

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJuYW1lIjogIkV4YW1wbGUgb2YgcGF5bWVudCBsaW5rIiwKICAicG9pbnRPZlNhbGVJZCI6ICJQT1MxODc3NTQyOTE1NjI1NDA0IiwKICAiYW1vdW50IjogewogICAgImN1cnJlbmN5IjogIkVVUiIsCiAgICAidmFsdWUiOiAxMDAKICB9LAogICJ2YWxpZFRvIjogIjIwMzAtMDUtMTFUMTI6MDA6MDAuMFoiLAogICJtZXNzYWdlIjogIlBheW1lbnQgZm9yIGd1aXRhciIsCiAgIm5vdGlmaWNhdGlvblVybCI6ICJodHRwOi8vaG9zdC9ub3RpZmljYXRpb25zL3JlY2VpdmUiLAogICJub3RpZmljYXRpb25VcmxQYXJhbWV0ZXJzIjogewogICAgImV4YW1wbGVLZXkiOiAiZXhhbXBsZVZhbHVlIgogIH0KfQo.C4lzvgzkKyPEJ6khviZ9mCG1QZW8ikoWgmIaFAsqxwZQAKAZI1RDQABFQYZczUrz0CyJVXu4EeOPNdF1IZs-z1PyyNa1QtozFtc6IzD6TYIEqThv3wgLyquR14sdBHP3OJiOT18-PAkGFXj2siZ5SyitGRkivJGg7toZg_f2E0DLApQZHMtWrvp1wwxHro-VMA6K_aYEK79VtrVxP7raOqjzytzOqkHETeZ499o-WxmpEh__oJZNLsDgryf9C-S3s5FBoV9JInxzLC_gEdQ136qNzvSWPecJnvFzDyudacg8iv9fvw3aZGNohsUGodkAN022-k7stxtdanfblDwQ1w

After decoding JWS, a JWS Header and JWS Payload containing the minimum data message are received. An asymmetric algorithm RSASSA-PKCS1-V1_5 with SHA-256 (RS256)is used for the signature. In order to verify the signature, a sample public key should be used:

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvFDG9DP6TT3nfLFCjQu/ JKoE/dur02BZfiWMFrft6I4Vrz7xpd272jE5i409z/JkyA0pk4lSUcGbraxllgs/ us8zNpRPZMsRSDmQtwXKS7SgLrJ+eJGZ0mVWG1ESE4dyLoO3YQgo3JV7xOlCNHyi 35eycwuV6aU2nQ1GDsv8UkMwVt6kZVb/avuFbmoBsOagmMZsYGfyRg0fFMfL/C9f tBKWX7OZsa0aGSB7Fe5qr55Se3NbvM5bDeRU9HDDUDTM+V4SDj+DVdnKZcPfOcVF Nig6+M7fWZ397VJA/xtXrbDY1D+gpvukMgB/FXBVfmQuKRv2AwIrA/S3Ib2IwiXD bwIDAQAB -----END PUBLIC KEY-----

To verify the response received from Conotoxia you need to use a public key provided by the API GET /jwks.

Communication with Partner

Example API response body:

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICJwdWJsaWNJZCI6ICJQTEsyNjY5MjU5Mjg4MzUwMDIwIiwKICAidXJsIjogImh0dHBzOi8vPENPTk9UT1hJQS1MSU5LLUhPU1Q-L1RPaElhazBUVGkiCn0K.qCS94aff1p95aU9tX4i0w2b4S1YUPnZyF_XRrjmWAxgms3cu1rfoWYBcjUnARQB3HOKRvI1G3Z8iO-INLBjAZ9kiLSjVIyYe_X5-1ksyyL2Rq5i6JZj8xGUB3U1D_cxHjt-B-hA81UsnVn2fRzsKsiYlGglJtaaGn6uc8KxSOiHuf8L0H4_tgZbHc51rk5LWRnQU3l5QiDuLGi5I5HHh4-_7BWBJWPLZHGYNaNj85hRHok-KvQ3vrlYxo1b1ZXb--lMP8MgpDn_SdrNOCh_hOi6dhq5T7QuvVNFDuiPy6PZUHmuMXQrrFGTVKjVlvY1Lu2TcnOciZourdkNrbi5FFQ

{
  "publicId": "PLK2669259288350020",
  "url": "https://<CONOTOXIA-LINK-HOST>/TOhIak0TTi"
}

Response headers:

HTTP/1.1 201 Created
Content-Type: application/json

HTTP/1.1 201 Created
Content-Type: application/jose+json

JWS Header

{
  "alg": "RS256",
  "typ": "JWT",
  "cty": "application/json",
  "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk"
}

JWS Payload

{
  "publicId": "PLK2644434971258604",
  "url": "https://conotoxia.host/w2XGqM9RWV"
}

All messages, answers and errors sent from the Conotoxia Payment link system to the Partner's system are sent in JWS format. Examples included in the documentation are provided in the decoded form for simplicity. In order to verify the received message, Conotoxia public key has to be obtained, and the authenticity of the gathered data has to be confirmed with this key.

Authenticity of URL parameters

Decoded data parameter (JWS Payload section):

{
  "paymentId": "PAY893669703633781",
  "externalPaymentId": "464/46846/45",
  "result": "SUCCESS"
}

After redirecting the User to the Partner's website, the Conotoxia Pay system places, within the configured URL, additional parameters defining the User's payment processing status. In order to ensure authenticity, these parameters are signed.

An example URL is presented below:

https://shop.com/success?data=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJwYXltZW50SWQiOiJQQVk4OTM2Njk3MDM2MzM3ODEiLCJleHRlcm5hbFBheW1lbnRJZCI6IjQ2NC80Njg0Ni80NSIsInJlc3VsdCI6IlNVQ0NFU1MifQ.S83VbMBroVHrAVfXs-tk_Q3BdulpAj3lni0vdegxZ7zCQHhJuIU_DYCFQ3OTG5-EHTJ6zzsmLjjzTw5S8XVy96MXQfHbJKY-jVWEAEB5mRiLgJMn4PssQRLgaGwWbhbFbvD5qqPCFpIz96-FWnkvoxuPaa86Ywfdhd-aPAZ43m3afIAXaKOt9Iy5A0fmsbtZsiwAtrFYMmPoNZcEl02NZ9paIaJ8RXaoU4oTKgMEVjZECQ4smqfnpVg7UD1UIw54F_NaTppx0fAAIZYp5n9lzT9-DwXMe875AbH0ZzRq6-500fSCmJQc3_ym9bM8Xa5gbKSlNQrw2t4pjxJkXbPOGw

Linux

Installation of the required software

To generate the public key it is required to use openssl software.
The process of installing this software is described in the following steps:

Open up console
Depending on distribution, install openssl using package manager with given command:

Distributions based on Debian (Ubuntu, Parrot OS)
sudo apt install openssl
CentOS
sudo yum install openssl

Generating the key

Open up console
To generate key pair enter the following commands:
openssl genpkey -out "private-key.pem" -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl rsa -in "private-key.pem" -out "public-key.pem" -outform PEM -pubout
The public key is in "public-key.pem" file

macOS

Installation of the required software

To generate the public key it is required to use openssl software.
The process of installing this software is described in the following steps:

Open up Terminal
To install openssl it is required to install a package manager for macOS called homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
To install openssl using package manager enter the following command:
brew install libressl

Generating the key

Open up Terminal
To generate key pair enter the following commands:
openssl genpkey -out “private-key.pem” -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl rsa -in “private-key.pem” -out “public-key.pem” -outform PEM -pubout
The public key is in "public-key.pem" file

Windows

Installation of the required software

To generate the public key it is required to use openssl software which is part of a libressl software delivered by OpenBSD for Windows.
The process of installing this software is described in the following steps:

Download libressl from official OpenBSD site:
https://ftp.openbsd.org/pub/OpenBSD/LibreSSL/libressl-2.5.5-windows.zip
Extract libressl-2.5.5-windows.zip archive

Generating the key

Navigate to extracted folder libressl-2.5.5-windows/x86/
Run openssl.exe
To generate key pair enter the following commands:
genpkey -out “private-key.pem” -algorithm RSA -pkeyopt rsa_keygen_bits:2048
rsa -in “private-key.pem” -out “public-key.pem” -outform PEM -pubout
The public key is in "public-key.pem" file in the current directory

Adding public key

POST <CONOTOXIA_HOST>/public_keys

Example Request

curl -X POST \\
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \\
     -H "Content-Type: application/json" \\
     -d "@public-key.json" \\
     "<CONOTOXIA_HOST>/public_keys"

public-key.json
 {
  "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnIo4OMp7I5ugVgGQquUL\nFFdC0m1sL+1e7M1zX8lobKPJpQwApDKaEFTBWjrK5aXvzAsxqKzKzG3yUCSGqa/f\nhuzdzs3kBlvIFCPwk5dM5uc5v2+2W0SF0/8lF3NBUjK2jz8s3Nyb3cCWCfysRF+1\nKhF/4ushqX4spCraIU2GkavZ6ETn/Oyfu1fJnZSuH16fwj2OwGsFnTUHam5yrihn\nhtxIkp4eUbhBOkjMMwb4XLygD1dlcg61Pbe60dmuwV+ZWQzfoi4QzlZd9kpePEva\nbPar+AUItKilx5XvNm86PLGBbcsGIMhtew019UP0MrgF1S2/99ZsF2V76haipaXS\nkQIDAQAB\n-----END PUBLIC KEY-----",
  "sampleData": {
    "decodedText": "test",
    "encodedText": "HHjI8WE+jlc/K7vgoYCAqe0NlIGpEHkIcx7iUze2T2hOMOpVogtAUq2XJLDWIkJ6kOIFAfYWrCfXullMIfRKix7ch9CHnBTGg0e0DHOZEw42C/50YhMzg1GpfLSJutQpOMU/KEjSXdvuJiKwngHWqpvJTxHTYJkPkLHzUzANz3iB1XB8KBepnHBW2WQ8SUBb8qw27AD1Gc6bySIgx8OoFSpZAsyDQanPtz/TkYBpakakRdw0ISc/cAM8KKTjOxTbHOwWcNDlwAmoBNS+eUGeH/yNBwjPnK1TS0yhmdgrerIrJ+yZm1VI5EHPbzWMBWx142LE/M9d9AEozAMYCUtOlg\u003d\u003d"
  }
}

Response headers:

HTTP/1.1 201 Created
Content-Type: application/json

Example Response

{
  "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ"
}

To enable secure communication between Conotoxia and the Partner's system, the Partner must provide a public key to verify the messages sent by the system. The public key should be provided in PEM format by calling the POST /public_keys resource.

Resource

POST <CONOTOXIA_HOST>/public_keys

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization chapter.
Content-Type	application/json	Format of request body data.

Request body

PublicKey object containing data on the public key

Field name	Type	Required	Description
pem	string	YES	Partner’s public key.
sampleData	object	NO	Object containing sample texts for public key verification.
sampleData.decodedText	string	YES	Sample text sent to verify the accuracy of the public key.
sampleData.encodedText	string	YES	Sample text from decodedText field signed by private key with SHA-256 signature.

Response body

Field name	Type	Required	Description
kid	string	YES	Partner's public key identifier.
status	string	YES	Partner's public key status.

The status field can take the following values:

Value	Description
ACTIVATED	Public key is active
INACTIVE	Public key require activation
REVOKED	Public key has been revoked

Getting public keys

GET <CONOTOXIA_HOST>/v2/public_keys

Example Request

curl -X GET </span>
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" </span>
     "<CONOTOXIA_HOST>/v2/public_keys"

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

HTTP/1.1 200 Success
Content-Type: application/jose+json

Example Response

{
 "data": [
   {
     "kid": "chi09N6Bog_0IvtrahDhZRGF7kiHTAhQaIm4x_wdpQU",
     "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoPYw28jrN71VoWHfSkTR\nb4v8OdYMjwZRs2dg5vPZjv0xryNAqHpHYP5+SCpEz6YRFGzuCWhqkNgSKmZgLBxv\nBVJt8YqZOtbnB4as/4TI0dy73YUmw00LYXLTcrS6al6OFtC4SehUREgoVG9V8Hlf\nx9T0bnNOW5R0z3LvkC+Y8e1Gm+xtX+K5uX00md5TI1jk5GqoE9D7cuv5mBX50Igi\nzMqbZYttu/gdA3TWD6JnceMU2WPKJDLowGN4RnUtQJQiApfRQZDPblB+9AKJkiTy\n8N4g9hAVmKbwC3cehO1vMB7ujOlJrNAXjh1rO7B3OJQ0JXcpb2UhrPZ/DIuRdLvX\n6QIDAQAB\n-----END PUBLIC KEY-----",
     "status": "ACTIVE"
   }
 ],
   "pagination": {
       "first": true,
       "last": true,
       "currentPageNumber": 1,
       "currentPageElementsCount": 2,
       "pageSize": 10,
       "totalPages": 1,
       "totalElements": 2,
       "pageLimitExceeded": false
     }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJkYXRhIjpbeyJraWQiOiJjaGkwOU42Qm9nXzBJdnRyYWhEaFpSR0Y3a2lIVEFoUWFJbTR4X3dkcFFVIiwicGVtIjoiLS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbk1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBb1BZdzI4anJONzFWb1dIZlNrVFJcbmI0djhPZFlNandaUnMyZGc1dlBaanYweHJ5TkFxSHBIWVA1K1NDcEV6NllSRkd6dUNXaHFrTmdTS21aZ0xCeHZcbkJWSnQ4WXFaT3RibkI0YXMvNFRJMGR5NzNZVW13MDBMWVhMVGNyUzZhbDZPRnRDNFNlaFVSRWdvVkc5VjhIbGZcbng5VDBibk5PVzVSMHozTHZrQytZOGUxR20reHRYK0s1dVgwMG1kNVRJMWprNUdxb0U5RDdjdXY1bUJYNTBJZ2lcbnpNcWJaWXR0dS9nZEEzVFdENkpuY2VNVTJXUEtKRExvd0dONFJuVXRRSlFpQXBmUlFaRFBibEIrOUFLSmtpVHlcbjhONGc5aEFWbUtid0MzY2VoTzF2TUI3dWpPbEpyTkFYamgxck83QjNPSlEwSlhjcGIyVWhyUFovREl1UmRMdlhcbjZRSURBUUFCXG4tLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0iLCJzdGF0dXMiOiJBQ1RJVkUifV0sInBhZ2luYXRpb24iOnsiZmlyc3QiOnRydWUsImxhc3QiOnRydWUsImN1cnJlbnRQYWdlTnVtYmVyIjoxLCJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsInBhZ2VTaXplIjoxMCwidG90YWxQYWdlcyI6MSwidG90YWxFbGVtZW50cyI6MiwicGFnZUxpbWl0RXhjZWVkZWQiOmZhbHNlfX0.kgvAN_OcEzNMYCkVJ920pSnZYWCk0c7nxjhtCAoHb01BZUpJZDHQaoCO-Ge8ZAFOHxsxptQhobRTx-pHfGvNpzAzLWlQm7fiUMW7lgc72jY_LJ7Dh7j8QMS5w-ZsF0NdzAi0CFyuCqWF6W7_KEFch2dE0PAHbi7cannDWmVbAKZjHSMMi2e4tqADxRQzrjt98US238m5LerQqjZCTSzogbllCIRKWnpOlhvmqCOcmBqFGioP3GRPsiJO6ZfyXvi7CtBV5NQGw1avGCOyxFZJyH8Pkqr8jVQlUyPQP9lcm43cntub31qhkHuwIJg8Jk_GgNCFIFBmYKeGXNzkhLUcMA

Added public keys may be verified using the GET /v2/public_keys resource.

Resource

GET <CONOTOXIA_HOST>/v2/public_keys

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization chapter.

Query parameters

Field name	Type	Required	Description
pageNumber	Number	NO	Page number.
inStatuses	String	NO	List of statuses that have to contain public keys status.
notInStatuses	String	NO	List of statuses that cannot contain public keys status.

Response body

Data object containing the list of added public keys

Field name	Type	Required	Description
data	Array	YES	List of objects of the PublicKey type.
pagination	Pagination	YES	Metadata of the returned page.

PublicKey object containing information about the public key of the Conotoxia

Field name	Type	Required	Description
kid	String	YES	Public key identifier.
pem	String	YES	Public key.
status	String	YES	Public key status.

The status field can take the following values:

Value	Description
ACTIVATED	Public key is active.
INACTIVE	Public key require activation.
REVOKED	Public key has been revoked.

Pagination object containing metadata of the returned page with public keys

Field name	Type	Required	Description
first	Boolean	YES	Defines whether the returned data are on the first page.
last	Boolean	YES	Defines whether the returned data are on the last page.
currentPageNumber	Number	YES	Defines the number of the returned page.
currentPageElementsCount	Number	YES	Defines the number of elements on the returned page.
pageSize	Number	YES	Defines the page size.
totalPages	Number	YES	Defines the number of available pages.
totalElements	Number	YES	Defines the number of available elements.
pageLimitExceeded	Boolean	YES	Defines whether the page limit has been reached.

Getting Conotoxia key

GET <CONOTOXIA_HOST>/jwks

Example Request

curl -X GET </span>
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" </span>
     "<CONOTOXIA_HOST>/jwks"

Response headers:

HTTP/1.1 200 Success
Content-Type: application/json

Example Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "zC4j4AchdzwKXS_Mqsh4AfwVySuGsFggO_2xv5tuszk",
      "use": "sig",
      "n": "hFava6Gd2uyA9XHmD7IIxiKD-S2vBcJ0QtgjodtvDeI4y3r5Ab_s_XMvTvbdSkCf0nmK84UwWwayQwnTboafvktCRndfnvSXWCVClgiVWJmnNibPhtsMI_uelmc99OjtPM93UZ6_yiohi1mKpC_w8MygxHX7R3rFMxssO5h-qXPfjWYWAiC0-B_Vf592E52N-dOF_yUi5hAP14gFbPv_LSWn2dSWkg2i6n5lTL6QzNQueBw3Q04odYXrbALPm1M0ucwgDewWW8LTzRAsqKwIeY9iTblq9ywxnExbq5qORgtNVk3zunqEYRKQfJIINFZgJSmqxxAfvnzlJyvuih97zQ",
      "e": "AQAB"
    }
  ]
}

To verify messages received from the Conotoxia system it is necessary to have a public key of the Conotoxia system. In order to obtain the key, the GET /jwks resource should be used.

Resource

GET <CONOTOXIA_HOST>/jwks

Request headers

Name	Value	Remarks
Authorization	Bearer <access_token>	Access token to authorize request. Described in Authorization documentation.

Response body

PublicKeys object containing the list of public keys of the Conotoxia system

Field name	Type	Required	Description
keys	array	YES	List of objects of the PublicKey type.

PublicKey object containing information about the public key of the Conotoxia

Field name	Type	Required	Description
kty	string	YES	Key type.
kid	string	YES	Public key identifier.
use	string	YES	Use of the key.
n	string	YES	Standard PEM module.
e	string	YES	Standard PEM exponent.

API errors - technical

Description of errors returned by Conotoxia API for all shared resources. Returned errors are signed (more information)

400 Bad Request

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "title": "Bad Request",
    "status": 400,
    "detail": "Unexpected character ('f' (code 102)): was expecting comma to separate Object entries"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJCYWQgUmVxdWVzdCIsCiAgInN0YXR1cyI6IDQwMCwKICAiZGV0YWlsIjogIlVuZXhwZWN0ZWQgY2hhcmFjdGVyICgnZicgKGNvZGUgMTAyKSk6IHdhcyBleHBlY3RpbmcgY29tbWEgdG8gc2VwYXJhdGUgT2JqZWN0IGVudHJpZXMiCn0K.aqKQ7MYMrV_EduhtErA131uAszFsyU5IQsMX9ixuKKXAx1LuyvhU51rTOr0nio0Wk1Dk8w2pztyJuKt_qWyr3XcDmZtuRbS0yrbmkUyzh-nKToA93YtWhwiASoGcafIDkHqGM3gr3DmhybfzFNW-5kpfNa0W7yE8TXx3HxZLclfp10yKfOdF0OvNwJ7OEWZ-oPbhj0Zer9bbxM_qtEQui9kKQnt0cKuGlzv75jY4J4_7jD6ASanBb718cfi0zCLT3yPRWjAfmF7Fw3S9zRUeyve8DobDs6aysp-CjqZ6QrlYfYz1KLQteJtzAYb9adjAZdFCw58_1z4cHvjKLlt71w

Returned when a request has an incorrect structure.

401 Unauthorized

Response headers:

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

HTTP/1.1 401 Unauthorized
Content-Type: application/jose+json

Example Response

{
    "title": "Unauthorized",
    "status": 401,
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJVbmF1dGhvcml6ZWQiLAogICJzdGF0dXMiOiA0MDEsCn0K.h8aLGDXvIOL0POM0zHsM91FNtN7vU_ZZxAq0s8be7EnAVFHDZLt0qLsBdsVY-R6S7qf_sCBSse9sKMnhRo1EDlXN1_cfU758GH_rZTfgXAdQmiDOt2d1gxD95VO4ZcJ9nW0_efn7O1nY4MRHw-MxNXMtoZ-ls8JpzTMYcARyQ4IAlruSJiM2n06n16MEfD_zyAKzAEzNNOHN2nai1RLiTZKHdCk9H1nCI4tjjq35ZrhP2EaDNhzbAQSTVudncKbbJXriJUs_PpJHN5K_sSupFTFVoWEQvfor2sBsbtLyPyFUG63eqYID2ewkmJyxnHW1JzdhvrEeceyeOYil8GnRbQ

Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

403 Forbidden

Response headers:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

HTTP/1.1 403 Forbidden
Content-Type: application/jose+json

Example Response

{
    "title": "Forbidden",
    "status": 403
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJGb3JiaWRkZW4iLAogICJzdGF0dXMiOiA0MDMKfQo.kFe80Z8J31U-9vi3g1XFW1DRuY1fKXq-jFSCdwA8CsfCa1bvgL-dhgFP0_042_ngSnPtBvpUdVBd1AN87moe6hDFj0xmUkutvjWuDjwvJE6QYVQnuuFvGRJttyoi909kOOoKHDbZo9H6GdYd-B5btw4odPwtdQFadNm8TCW_YwEqaW4BX4tgNZ4pAzG_NGXwxTazTxoJ4sQSutHff9fu7MCzpx8Zh9gB6vfaK61YWOR1gTfstvF5_LNQ1f3d_VGx3rybO9Q0mz5hOsSxtrDTAT9von4kTBCTXy297GUQ_u7y-ZLHRvMa7v2bUZPg320-NdhOGnGtqR_U2YlD4e9ySw

Returned when the Customer does not have access to requested resource.

405 Method Not Allowed

Response headers:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/problem+json

HTTP/1.1 405 Method Not Allowed
Content-Type: application/jose+json

Example Response

{
    "title": "Method Not Allowed",
    "status": 405,
    "detail": "Request method 'PUT' not supported"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJNZXRob2QgTm90IEFsbG93ZWQiLAogICJzdGF0dXMiOiA0MDUsCiAgImRldGFpbCI6ICJSZXF1ZXN0IG1ldGhvZCAnUFVUJyBub3Qgc3VwcG9ydGVkIgp9Cg.UoepUd1CRzsk5MYCnXFO1Szp2qQSsGMJsctNwCP-oSCcnqK5fFLdFcl4I0oCB_cDM2jxtxk_aMIplqurrZewbWZkurNtuAu410HZa9XqzSyXXwS8_BWT92ZNxh0j4sU9tM0I0D4zGeOiTco0RW2R-uxghu_RdED64ffz55QiaGxgnJ51EUaBqrTk1HBDJqFD76vF7FV7AUTnXvPLIKw0hr3RQK7PLkSHPnYzLgTpmngJE1iW_7hZq4Fx5EHCWPE0t03LpzqfgXcucazv_WX1SWTx7CIaR_abK_rTQB36y8vIret6RBA76l3nu2KJc1UMyMloeTJTHkwREGIOGAi5Rw

Returned when the method called on the resource is different than defined.

415 Unsupported Media Type

Response headers:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/problem+json

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/jose+json

Example Response

{
    "title": "Unsupported Media Type",
    "status": 415,
    "detail": "Content type 'application/x-www-form-urlencoded' not supported"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJVbnN1cHBvcnRlZCBNZWRpYSBUeXBlIiwKICAic3RhdHVzIjogNDE1LAogICJkZXRhaWwiOiAiQ29udGVudCB0eXBlICdhcHBsaWNhdGlvbi94LXd3dy1mb3JtLXVybGVuY29kZWQnIG5vdCBzdXBwb3J0ZWQiCn0K.M1u8nmjVjInC4fhzhhS_iOeXvT_G-lRm2fAcbQTTMIfx8z9CHYulK6C06NSoCweqAsW7RPuTj2KhZof-TEg4e3p1pG__aHJd2aMmpLIcWSUXFlZBmqT86j6qvoReuxmq3bO35LFL_4w1ebJ7I7Rz9mI96Zm7h3VfrzaGtYkbRO1PtBstvMp-5BFmLVhSnqgtijCmVF24Kz54DGpcTOUPSxoUPqJXVddXXBwufCRWx0LYWZ-kZkjsomcazcHelxxVjltwlrlqF-QewFcoFb9Agdf92bEU7Zahbgdj4vFcFDwU83E2TffGuzqEsws4RGAo9bdcLfjd_-eSeOAexeh9Ig

The sent request body is of the wrong type.

500 Internal Server Error

Response headers:

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

HTTP/1.1 500 Internal Server Error
Content-Type: application/jose+json

Example Response

{
    "title": "Internal Server Error",
    "status": 500
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJJbnRlcm5hbCBTZXJ2ZXIgRXJyb3IiLAogICJzdGF0dXMiOiA1MDAKfQo.e1kg08PJWBRc0r4skb_bRDIzhSVbZypHF0gT7V8-WjmCHpTpuJG1Nss6td1zcIHsq3Cf4v1W0Pe8FIC-evb8ubOFiZf3m8zpk1zF5_v809dLu7QAhe8P2xeLCB5mntGAPVbwN7b6B4vtISy7L0aThpzBQV6zKZC6NNX__JyfKnSafSqh-oSIJWlcQaawv-ORsSjtCDIchBkvZrqVwdnqj5Ea07r9kUWtP8FD_EAopDSA2_YQDhvuOJ-XCdYao0D6wCbhHFwDlCPlQsi0rFLovHl6YiJdfT1UX745CtIsAFUCK4G2Rn_onKE9_EZFtHVPkp9ACbNOMHjuEHJ-ILYDNw

An unexpected error occurred.

503 Service Unavailable

Response headers:

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

HTTP/1.1 503 Service Unavailable
Content-Type: application/jose+json

Example Response

{
    "title": "Service Unavailable",
    "status": 503
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0aXRsZSI6ICJTZXJ2aWNlIFVuYXZhaWxhYmxlIiwKICAic3RhdHVzIjogNTAzCn0K.piivBKphgtTsFMjAEVIwFqO25R0lDwXSogRcWDpGL9QU5T43FlMX4s06D456fDzGNjdFhThy5w1XkgUXwOpL3kS1L3Z58KXcULte_EF7_gIs7l34Q37Ed6Ie5LuzKHScHswWV9HWfoie3xwf9c_Xe_gxoVWX8S7vXkUA8Ejwkd_da7xiXz5sD_PDGPf2lKHiFXTc4IVFNouSkjNEKhmjp6aytEPSj-gj3NAKjL9zviMe9e_dorkyp8QGcIhsAOU4Gw2frP4ydPsZE6HAseK5o8t56Y9Z8OQbOuMwdJsWyiWCHKknOgCID5arXVxfbjeo71voTnX90TxZ2CGiHcrIQQ

Service is not available.

API errors - business

Description of errors returned by Conotoxia API, whose type is defined by the type key. Description of errors returned by Conotoxia API for all shared resources. Returned errors are signed (more information)

invalid-jws

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "type": "invalid-jws",
    "status": 400,
    "title": "Invalid JWS",
    "validation-errors": [
        {
            "message": "Header 'kid' is missing",
            "message-key": "KidHeaderMissing",
            "context-key": "jws"
        }
    ]
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtandzIiwKICAic3RhdHVzIjogNDAwLAogICJ0aXRsZSI6ICJJbnZhbGlkIEpXUyIsCiAgInZhbGlkYXRpb24tZXJyb3JzIjogWwogICAgewogICAgICAibWVzc2FnZSI6ICJIZWFkZXIgJ2tpZCcgaXMgbWlzc2luZyIsCiAgICAgICJtZXNzYWdlLWtleSI6ICJLaWRIZWFkZXJNaXNzaW5nIiwKICAgICAgImNvbnRleHQta2V5IjogImp3cyIKICAgIH0KICBdCn0K.lKX99YN0Z3uzdisA2ZR3RCCAZzLT-AFlJvh4722PfGkxBk7HTNFN1pQQftLqGTUzJrJPWKE8dPkybULQ8ed3f-AZUAm-vsdvjLH6mdTPmAGV_xBaw_H564f4xt-EsEeRuggykqqEVwm-OuuRp4uC9wDN26p9-MAGVmvBljZH63E7V3o02M2XMGe3t1NUJJqkLyfCEEdxhLNLPjjKWWZNbY9DhLGW7Z31a51E6dUKb6ugIIm2INCDF5UCQl2XtIfbi5HpUbVTj1hoxveYO0hebbspIPhUeRHCh2O9N1BA_doNtk7zp_a2k59p98Wm-JJnfBsgILsLmCW640y5eX3wbA

Returned when the format of the JWS request is incorrect:

header kid is missing (message-key: KidHeaderMissing),
header alg is missing (message-key: AlgHeaderMissing),
header alg contains unsupported algorithm (message-key: UnsupportedAlgorithm).

invalid-pem

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "type": "invalid-pem",
    "status": 400,
    "title": "Can not read public key from PEM",
    "detail": "Can not read public key from PEM"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtcGVtIiwKICAic3RhdHVzIjogNDAwLAogICJ0aXRsZSI6ICJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIsCiAgImRldGFpbCI6ICJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIKfQo.EVkuM9ARnwFLxQI8D4sTN0RTBM3j0cjW0Tkj5tPX8R3N7_Xd2TwPrsTdw_1-E-kcDb8d7UN0mUUVa-l7FGdwvNKp1W8HHsxSLBKfRZGzIQH0iwrFfi_IKLGA2c1lgNO6g0EMFX-CuK-Q9_0g2kPl4tY6pp5Ffs56cH-RVftJzfCAG-CfeVNMOEj9jf1d1127T-yfdzVVVP6utigLKSOgsCYbRzI8m0bEt6R6BZVsYxhuGF571VuAMi-cnOJ8ScxRkqRcNUAM4UskGO5WvZYRqVepVQSa9cYuPaTxvLyyQtdWh1egmgsVbPrYWBFTfb5Kwh898gdnzSV9DTEsaSZ0MQ

Returned when the sent public key is incorrect.

invalid-public-key

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "type": "invalid-public-key",
    "status": 400,
    "title": "Invalid public key",
    "detail": "Invalid public key"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogImludmFsaWQtcHVibGljLWtleSIsCiAgInN0YXR1cyI6IDQwMCwKICAidGl0bGUiOiAiSW52YWxpZCBwdWJsaWMga2V5IiwKICAiZGV0YWlsIjogIkludmFsaWQgcHVibGljIGtleSIKfQo.C2LdPezNwMytnd5LcpFEfPraqA9V-0GJPnnEIvltynTq2dzDeE37jyTbd85nxeH-EmpYU1Hm2JYhmyHZ_yRLMe9qhuocfPvsjNVVnbEuZ2dBcTG8aQ2v_02aUOApkO71WZ9rAhkGEQb2yW1wNAEf1c0lHomCaTZ7SX_6YcASRVoRLsrBPXj_fOcuc-9lQ7JAftFm51YjVN7QurwNov1iMVw_zf_ihoWSkGvhKF86_p5Biih5HAl6iMwN4K68m3ezRTZ1TEBmUpvwXn141t6f0SN9KKcNURuXAiyHf-pt2OSF9fZLJdRNJBKU5XuGCpEsmZHyXBPmPYOwku2sE_thnQ

Returned when adding a new public key, and the key is incorrect.

sample-text-signature-not-match

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "type": "sample-text-signature-not-match",
    "status": 400,
    "title": "Sample text signature not match",
    "detail": "Sample decoded text must have signed with SHA-256 signature"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6IjhIZFRlR21scUZRRW9IMVBzdlk1RTNRdVBOMG1yNUpKOTdlUjZnU202aVUiLCJ0eXAiOiJKV1QifQ.ewogICJ0eXBlIjogInNhbXBsZS10ZXh0LXNpZ25hdHVyZS1ub3QtbWF0Y2giLAogICJzdGF0dXMiOiA0MDAsCiAgInRpdGxlIjogIlNhbXBsZSB0ZXh0IHNpZ25hdHVyZSBub3QgbWF0Y2giLAogICJkZXRhaWwiOiAiU2FtcGxlIGRlY29kZWQgdGV4dCBtdXN0IGhhdmUgc2lnbmVkIHdpdGggU0hBLTI1NiBzaWduYXR1cmUiCn0K.cWbBEnJlFHPH0NtGIICSOQBa0d2zSuWUu5Cf6BPdY_RHp0rczKnNH_vqUBBjSmVRdDytV7fysqSEgrd94tinjD3-LPVLwQrK8XpRjrWyqMy-sT6V1KEydqRbhGQj9my3C5OIcsl2Daxb6wCmfrtfjCtLFnYYYrwjobtdrCwWRkbH1GhAruST7Zw1LYF8KGRSPyLjSjXpQc7hkAmm1FNFOw_FewJxw3yxdSBavzGZoJlTXylox7qfzap6nXlTHBor-sLAfz-QZE1pjQcrEXIIs_vaD5Me8OE869gNG3xIfhLgPN8mS5N8jbSCLJS9ZWoFuQQwb6kBlS4OsxhQxrNJpg

Returned when adding a new public key. Example message in the encodedText field: The text was signed with a different signature than SHA-256.

validation-error

Response headers:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

HTTP/1.1 400 Bad Request
Content-Type: application/jose+json

Example Response

{
    "type": "validation-error",
    "title": "Your request parameters didn't validate.",
    "status": 400,
    "validation-errors": [
        {
            "context-key": "name",
            "message-key": "null-value",
            "message": "should not be null"
        }
    ]
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICAgInR5cGUiOiAidmFsaWRhdGlvbi1lcnJvciIsCiAgICAidGl0bGUiOiAiWW91ciByZXF1ZXN0IHBhcmFtZXRlcnMgZGlkbid0IHZhbGlkYXRlLiIsCiAgICAic3RhdHVzIjogNDAwLAogICAgInZhbGlkYXRpb24tZXJyb3JzIjogWwogICAgICAgIHsKICAgICAgICAgICAgImNvbnRleHQta2V5IjogIm5hbWUiLAogICAgICAgICAgICAibWVzc2FnZS1rZXkiOiAibnVsbC12YWx1ZSIsCiAgICAgICAgICAgICJtZXNzYWdlIjogInNob3VsZCBub3QgYmUgbnVsbCIKICAgICAgICB9CiAgICBdCn0K.aitenhO0TCZ3MjnR9lbHB2hbFqsgurkRwxQ1kF2yLdgXAf9HjfYf2CkcxxPbExpX60qdPofKjN-BHw5oqF1f0uwILmCwbW-mVhhhc92_Ds0Uko-HwuaLOiaaIPnggEmHSi9LDxNCfvjikUJsA8ZNLrqoeTyKgTa7yRhJn5UC1aNZfOW9PB5iJwfHIkxcsj-R_QqMFiWbClnF_ABnDnfK__lFg9KdtDNp7vWQyYLDSL0NfNQtg2knHGZsWz-ivP9OKr1Fh2JxX3XM3JdcRiBjxrxI7p1Qkzb96-sc6ROJ-4z1u9KQfku5tiRtfpwsfenuyCJ9bzi5HjETZZlx682Mwg

Returned when specified request parameters are incorrect. The general example of validation error.

point-of-sale-not-found

Response headers:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

HTTP/1.1 404 Not Found
Content-Type: application/jose+json

Example Response

{
    "type": "point-of-sale-not-found",
    "title": "Point of sale not found",
    "status": 404,
    "detail": "Point of sale with identifier POS458963214589658 not found"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICAgInR5cGUiOiAicG9pbnQtb2Ytc2FsZS1ub3QtZm91bmQiLAogICAgInRpdGxlIjogIlBvaW50IG9mIHNhbGUgbm90IGZvdW5kIiwKICAgICJzdGF0dXMiOiA0MDQsCiAgICAiZGV0YWlsIjogIlBvaW50IG9mIHNhbGUgd2l0aCBpZGVudGlmaWVyIFBPUzQ1ODk2MzIxNDU4OTY1OCBub3QgZm91bmQiCn0K.n7SaLicwp5lp2VBvg14fJ2IX4kEseniW6FbQEIrbhzlLHR6jU0txTBU70gU8cbAKncRT2REDjH8itM36nhPIgL7KWqamvQcQGjQJcpojajP1Bt4hupXWRhRdafNLMddTNSddiij7_8-CAVIDaNqC8SO_ER1zpwd2sqgOXrZlkCt1Ia8xzKo2ckWYVmDuO371jputpXzrJt677XlecmJCMPU689eLBF3vxa-SzOw2yzB_1I-rZpoJ7GGpg2kJ_Ffwa_2qqcoQFEK2XVcxS8seAkDVFcmb2zjl60aKTXveDXT6cRNZAHtQdekWhnuxG2XXMt8RX_hyYa16a0AWBxncbQ

The point of sale was not found.

currency-unavailable

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Example Response

{
    "type": "currency-unavailable",
    "title": "Currency is unavailable",
    "status": 409,
    "detail": "Currency HRK is unavailable"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICAgInR5cGUiOiAiY3VycmVuY3ktdW5hdmFpbGFibGUiLAogICAgInRpdGxlIjogIkN1cnJlbmN5IGlzIHVuYXZhaWxhYmxlIiwKICAgICJzdGF0dXMiOiA0MDksCiAgICAiZGV0YWlsIjogIkN1cnJlbmN5IEhSSyBpcyB1bmF2YWlsYWJsZSIKfQo.GPSq5b40oONRFGtIsvP0h4XDfKKT0Ke59VUqkDnHW9Z3y7f7_5eR8r2mRMsqeEg0H8ztyqVa9aWOo98XK8ZShfU8kcMmJmnuO_WTSr-Ob1-zmYBqyC24gimVYFr498EiQsMBx-PYZmQgcxQRo8AR7oTfqUqb-xd8cMyuuA6TtVu_15h18ypF84w2BEP8nK3c1JnRTWqUtozPOBcgSlLmVro5f1QGrtkonMy52LRWA7zZl_dHMPKkUFrFzeHMSYl0iZTplqL-kcC-DKbsNEO8-ycTzpJMD9MbvVUuNawTVrmp8IpzLj5P8ULr37dmh_a9U4CXQMhw0ind8kTUhkLjyQ

The selected currency is unavailable.

point-of-sale-not-active

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Example Response

{
    "type": "point-of-sale-not-active",
    "title": "Point of sale not active",
    "status": 409,
    "detail": "Point of sale with identifier POS458963214589658 is not active"
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICAgInR5cGUiOiAicG9pbnQtb2Ytc2FsZS1ub3QtYWN0aXZlIiwKICAgICJ0aXRsZSI6ICJQb2ludCBvZiBzYWxlIG5vdCBhY3RpdmUiLAogICAgInN0YXR1cyI6IDQwOSwKICAgICJkZXRhaWwiOiAiUG9pbnQgb2Ygc2FsZSB3aXRoIGlkZW50aWZpZXIgUE9TNDU4OTYzMjE0NTg5NjU4IGlzIG5vdCBhY3RpdmUiCn0K.ev1PY5WC2xu5YQJ3RDmwZjXkuUUxGyq8NvIdi_MGRsDVvyTGqdRRcGP9-qtgIYcBA-ifuvjHvnd2KV5JGFsjB8X-TMccc2-koNhz69z4LGQygYW8P82OmcykOyarVVsm57hTsTm27YkPF8ick7h_ll_O8DmvJtmKn3N7tkKDl1ywj_oZ0xLRNUX1KwQQbHH3IMrfLXIigcw4Lt45e41usH8SfyqKN8Ko8bOpB5ejDm7w8bsjeHz931rHOV0wuikR87K9qzVOrQn8FJu5OJuUjIBKAIWfftfBoNvgPmVdXqmD6mVVsTBQs-gCakI1aLaw_AVgGtmJ61UwGhX8-w53PA

The point of sale is not active.

transaction-below-limit

Response headers:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

HTTP/1.1 409 Conflict
Content-Type: application/jose+json

Example Response

{
    "type": "transaction-below-limit",
    "title": "Transaction below limit",
    "status": 409,
    "detail": "The 0.01 EUR transaction is below the 1.00 EUR limit",
    "limitType": "CURRENCY",
    "money": {
       "currency": "EUR",
       "value": 0.01
    },
    "limit": {
       "currency": "EUR",
       "value": 1
    }
}

eyJhbGciOiJSUzI1NiIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJ0eXAiOiJKV1QiLCJraWQiOiI4SGRUZUdtbHFGUUVvSDFQc3ZZNUUzUXVQTjBtcjVKSjk3ZVI2Z1NtNmlVIn0.ewogICAgInR5cGUiOiAidHJhbnNhY3Rpb24tYmVsb3ctbGltaXQiLAogICAgInRpdGxlIjogIlRyYW5zYWN0aW9uIGJlbG93IGxpbWl0IiwKICAgICJzdGF0dXMiOiA0MDksCiAgICAiZGV0YWlsIjogIlRoZSAwLjAxIEVVUiB0cmFuc2FjdGlvbiBpcyBiZWxvdyB0aGUgMS4wMCBFVVIgbGltaXQiLAogICAgImxpbWl0VHlwZSI6ICJDVVJSRU5DWSIsCiAgICAibW9uZXkiOiB7CiAgICAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICAgICJ2YWx1ZSI6IDAuMDEKICAgIH0sCiAgICAibGltaXQiOiB7CiAgICAgICAiY3VycmVuY3kiOiAiRVVSIiwKICAgICAgICJ2YWx1ZSI6IDEKICAgIH0KfQo.kBtkAqot-zOfwwdClwCM2djnpECrJWV8785DtdLosAbU2AUDsZwiReB3HoqCt20HQ-0_uOcRZ8010lgZmvjS_rlTOjc_Xq_-WUSXvnewGOZ1nHEfKVjByaVgI7kp_rOvRt1LT57FdGSUk32IyQf5CRw4Th8B2vdBLOCdebW-lAqAPpHxFnoQ8WGTO3SnGiBL5Uzy-euTR5oANtFrz588yf2VtJstrzLXwa5ODl8On2RJgX_R00TKcQDEg2Ekpj8tuITjuThtrDEvPcE-icEW38GK9nnulrsO15AmMUNYzFOYwX2ho7zhG439J_6NTczKjLwsDwHqsKMO2M7A-AvOgQ

The transaction amount is below the limit. Possible limitType field values:

Value	Description
CURRENCY	The indicated payment amount is below the defined value for a given currency.
COMMISSION	For the selected payment method, the fees exceed the transaction amount.