NAV Navbar
cURL unsigned cURL signed

Introduction

This documentation includes a description of business processes and REST API methods made available via Conotoxia Pay. The API enables simple and safe automatization of payments and refunds by the Partner's system.

API can be used for:

How to start?

To integrate with the Conotoxia Pay system, the Partner needs:

Creation of a currency exchange order

To create a currency exchange request, simply follow a few easy steps:

  1. 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 Pay API.
  2. With your private key, you must sign the request body (an example of the request can be found in the chapter Creating a currency exchange). Note that JWS, which will be sent to Conotoxia Pay API, should have a public key identifier (kid) in the header section. It will be used to verify requests by the Conotoxia Pay system.
  3. Execute the request on the POST /currency_exchange resource by placing in the request body JWS data and setting the correct header according to the information provided in the Communication with Conotoxia Pay section.
  4. The received response should be decoded and verified following the information provided in the Communication with the Partner section.

Authentication

In order to use Conotoxia Pay, it is necessary to process authentication. Each API request provided by Conotoxia Pay requires sending an Authorization header, which contains an access token called OAuth 2.0 access token. To generate the token, use the POST /connect/token resource. Authentication is performed using HTTP Basic, where the user name is api_client_id and the password 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

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"

Response body:

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

Enables obtaining the Conotoxia Pay access token.

Resource

POST <CONOTOXIA_OIDC_HOST>/connect/token

Request headers

Name Value Remarks
Authorization api_client_id:api_client_secret HTTP Basic Authentication.
Content-Type application/x-www-form-urlencoded

Request body

Parameters according to client_credentials mode

Name Value
grant_type client_credentials
scope pay_api

Response

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

Bank Accounts

Getting list of bank accounts

curl -X GET
    -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM"
    "<CONOTOXIA_HOST>/v1/accounts

Response headers:

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

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

Response body:

{
  "data": [
    {
    "id": "891575077715",
    "name": "Rachunek",
    "iban": "90249048727073537672584707",
    "bank": {
      "name": "Alior   Bank",
      "region": "GŁÓWNY",
      "swift": "ALBPPLPW",
      "alias": "ALIOR",
      "country": "PL"
    },
    "currency": "PLN",
    "isShared": false,
    "address": {
      "street": "Ulicowa   96/2",
      "postalCode": "65-001",
      "city": "Zielona   Góra",
      "country": "PL"
    },
    "isForbiddenCountry": false
    }
  ],
  "pagination": {
    "hasNext": false,
    "hasPrevious": false,
    "order": "currency+",
    "pageSize": 10,
    "pageNumber": 1
  }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJkYXRhIjpbeyJpZCI6Ijg5MTU3NTA3NzcxNSIsIm5hbWUiOiJSYWNodW5layIsImliYW4iOiI5MDI0OTA0ODcyNzA3MzUzNzY3MjU4NDcwNyIsImJhbmsiOnsibmFtZSI6IkFsaW9yIEJhbmsiLCJyZWdpb24iOiJHxYHDk1dOWSIsInN3aWZ0IjoiQUxCUFBMUFciLCJhbGlhcyI6IkFMSU9SIiwiY291bnRyeSI6IlBMIn0sImN1cnJlbmN5IjoiUExOIiwiaXNTaGFyZWQiOmZhbHNlLCJhZGRyZXNzIjp7InN0cmVldCI6IlVsaWNvd2EgOTYvMiIsInBvc3RhbENvZGUiOiI2NS0wMDEiLCJjaXR5IjoiWmllbG9uYSBHw7NyYSIsImNvdW50cnkiOiJQTCJ9LCJpc0ZvcmJpZGRlbkNvdW50cnkiOmZhbHNlfV0sInBhZ2luYXRpb24iOnsiaGFzTmV4dCI6ZmFsc2UsImhhc1ByZXZpb3VzIjpmYWxzZSwib3JkZXIiOiJERUZBVUxUIiwicGFnZVNpemUiOjEwLCJwYWdlTnVtYmVyIjoxfX0.C_ZtT-Kxk-y0ELEQ3bZDChaUyIdFNU0MC_Hrdpr_6slMySBskuQokFk0fOOxsQ7DmXXrnr015gU4qI-RETvqtcRkVrVwq18Yn0GdgztzL3VsEMbUA-5ya3mpfB9NTCcwviqfoOZcm6oxyzt2iYZcT8CRewPxhQ528OO0xS8NWaNUWyiECTjL_02gPJ2xGWAxI3tsvNOJrS3S6ykvtRmV8r_ohKTdlF_cCiqOuHo5MmehIJjRRIFu8Kt8iyrkVA5WtR5uzRK_qAbNRnHQY2UAhuFsh5zpk8gpW45v2I583iRkuf6o9C-YWhB9pTNppmYYZ1Mi7KlOsJ36KRqGk7e8iA

Gets a list of bank accounts with specified search parameters.

Resource

GET <CONOTOXIA_HOST>/v1/accounts

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Field name Type Required Description
isForbidden String NO Filters the list by forbidding country on saction list
id String NO ID's of bank accounts
currencies String NO Currencies codes separated by commas or one currency according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
pageNumber Number NO Page number.
pageSize Number NO Number of elements per page.
sort String NO Sorting criteria.

Sort field value for bank accounts

You can sort the following fields:

To sort in descending order by the bank account creation date, enter the following value: currency- or currency+.

Response body

Response object containing bank account data

Field name Type Required Limit Description
data Array YES max. 100 elements A list with elements of the BankAccount type.
pagination Pagination YES max. 36 characters Metadata of the returned page.

BankAccount object containing bank account details

Field name Type Required Limit Description
id string YES 12 characters User bank account identifier.
name string YES max. 128 characters User bank account alias.
Max 128 characters.
iban string YES max. 64 characters Account number
Max 68 characters.
routingNumber string NO 12 characters Routing number in U.S. bank accounts
Max 10 characters.
isShared boolean YES It is shared with other user
isForbiddenCountry boolean YES It is from a forbidden country
currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
bank object YES
bank.name string YES max. 64 characters Bank name
bank.region string YES max. 64 characters Bank region
bank.swift string YES max. 64 characters Swift code of a bank account
bank.alias string YES max. 64 characters Alias of a bank account
bank.country string YES 2 characters Country.
ISO 3166-1 alpha-2 country code.
address object YES
address.street string YES max. 128 characters Street
address.postalCode string YES max. 45 characters Postal code
address.city string YES max. 45 characters City
address.country string YES 2 characters Country.
ISO 3166-1 alpha-2 country code.

Pagination object containing metadata of the returned bank account data page

Field name Type Required Description
hasPrevious boolean YES Information that the previous page exists.
hasNext boolean YES Information that the next page exists.
pageNumber Number YES Number of elements on page.
pageSize Number YES Page size.

API errors

The GET /v1/accounts method can only return technical errors.

Currency Wallet

Getting currency wallet balance

curl -X GET
    -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM"
    "<CONOTOXIA_HOST>/v1/wallets

Response headers:

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

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

Response body:

{
  "data": [
    {
      "balanceAmount": 3.00,
      "availableAmount": 3.00,
      "currency": "EUR",
      "lastOperation": "2023-01-23T09:41:46.000Z"
    }
  ],
  "pagination": {
    "hasNext": false,
    "hasPrevious": false,
    "order": "DEFAULT",
    "pageSize": 50,
    "pageNumber": 1
  }
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJkYXRhIjpbeyJiYWxhbmNlQW1vdW50IjozLjAwLCJhdmFpbGFibGVBbW91bnQiOjMuMDAsImN1cnJlbmN5IjoiRVVSIiwibGFzdE9wZXJhdGlvbiI6IjIwMjMtMDEtMjNUMDk6NDE6NDYuMDAwWiJ9XSwicGFnaW5hdGlvbiI6eyJoYXNOZXh0IjpmYWxzZSwiaGFzUHJldmlvdXMiOmZhbHNlLCJvcmRlciI6IkRFRkFVTFQiLCJwYWdlU2l6ZSI6NTAsInBhZ2VOdW1iZXIiOjF9fQ.eJ9Bho73gqCUjaeDNA1lv0kE_SvIO0YBnHXAoZ948Apl5Fi2LlzEWq-tWVLcK8klzFDlXUBxCQxvwpt21gQFjQy64uKpJkFtkNAS51ZvO96tnQ7KDL7QM2izV3mp2olzZqsyHqFFVjPTuTrtvQahW2a4JsBFw6JXfW0bZON80SXuBLlo2rcn87ggLBnzLhIyjpjle1Pd2YmperFyqHv3PsjzAZPSj7rqZ75GQmVBMdsrQEkIl9IIsTJt9gzpMPCdRhC63o0kEEcrD8Pdbm0WBbzpIqPKUIwyu53Nxp7B2RyY2lcfjh57X2TE-TJ7nUjsFDjg25ZGwFB8Y6DkwQJxIw

Gets a list of wallets with specified search parameters.

Resource

GET <CONOTOXIA_HOST>/v1/wallets

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Query parameters

Field name Type Required Description
currencies String NO Currencies codes separating by commas or one currency according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
pageNumber Number NO Page number.
pageSize Number NO Number of elements per page.
sort String NO Sorting criteria.

Sort field value for wallet

You can sort the following fields:

To sort in descending order by the bank account creation date, enter the following value: currency- or currency+.

Response body

Response object containing wallet data

Field name Type Required Limit Description
list Array YES max. 100 elements A list with elements of the Wallet type.
pagination Pagination YES max. 36 characters Metadata of the returned page.

Wallet object containing wallet details

Field name Type Required Limit Description
balanceAmount Decimal YES max. 20 characters Available and locked account balance
availableAmount Decimal YES max. 20 characters Available account balance
currency String YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
lastOperation String NO Date and time in UTC format (e.q. 2023-01-23T09:41:46.000Z) of last operation on the wallet.

Pagination object containing metadata of the returned wallet data page

Field name Type Required Description
hasPrevious boolean YES Information that the previous page exists.
hasNext boolean YES Information that the next page exists.
pageNumber Number YES Number of elements on page.
pageSize Number YES Page size.

API errors

The GET /v1/v1/wallet method can only return technical errors.

Currency Exchange

Currency exchange order

curl -X GET
    -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM"
    "<CONOTOXIA_HOST>/v1/currency_exchange/transactions

Request headers:

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

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

Request body:

{
    "from": {
        "amount" {
            "currency": "PLN",
            "value": "10"
        }
        "type": "WALLET"
    },
    "to": {
        "amount" {
            "currency": "EUR",
            "value": "0"
        }
        "account": "98144984242767",
        "type": "IBAN"
    },
    "title": "title",
    "discountCode": "CXX111111111",
    "purpose": "",
    "natureOfPayment":""
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Iko5dS1SVm42TWNPekhQTkxDUUNOOE8xbUQ1VkYta0IwU0lCbjN3QXpxbmsifQ.eyJpbmNvbWUiOnsiY3VycmVuY3kiOiJQTE4iLCJhbW91bnQiOiIxMCIsInR5cGUiOiJ3YWxsZXQifSwib3V0Y29tZSI6eyJjdXJyZW5jeSI6IkVVUiIsImFjY291bnQiOiI5ODE0NDk4NDI0Mjc2NyIsImFtb3VudCI6IjAiLCJ0eXBlIjoid2FsbGV0In0sInRpdGxlIjoidGl0bGUiLCJkaXNjb3VudENvZGUiOiJDWFgxMTExMTExMTEiLCJwdXJwb3NlIjoiIiwibmF0dXJlT2ZQYXltZW50IjoiIn0.E7liLjtXzHFtgovE-3o2fIHRvpyJrMSMcYjnULcEtSqXsErYORmRGSc98FH1kbg-Gw_2djXlJmq_NnG2yOE3rjk_PPVIK42NuYAdH0PONTAuqyTkxE73SLb8epBJwyuKqXyFmFjbPG8e79CMif8v93Ai5fUcT0eAmhycnw-OElJh4P9EJHxYQQ-n8IKJ-sp4NjKXBotqrInoNwT62VWX8jDWjaLW0eurIvxbuuDermWLkinjwYR27nYioVezuUyIuOsiTjDD34KI80XsD2rRdMBUdzCcI_6i8z7ipoE-OBqWkdGwVWwj8EodO38PEdrD3ZF_cyPBfYwuvPFHVUEsfA

Response headers:

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

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

Response body:

{
    "from": {
        "amount": {
            "currency": "PLN",
            "value": 10
        }
    },
    "to": {
        "amount": {
            "currency": "EUR",
            "value": 2.3
        }
    },
    "token": "5faf392757db668aff4fc13a784bb79a6b7209eedc0583153230b247297c669b25ecf0bc9eb05d7eedc8ba291ade57747b7efe0a793addb74b71307bd7f3a3bd",
    "expirationDate": "2024-02-05T12:03:42.000Z",
    "validDiscountCode": false,
    "rateScaling": 1,
    "limitNativeAmountExceeded": false,
    "transactionLimitExceeded": false,
    "negotiateRate": false,
    "rateSell": 1.0,
    "rateBuy": 4.3482,
    "hasPendingTransactions": true,
    "exchangeRate": 4.3482,
    "exchangeRateWithoutCode": 4.3482,
    "exchangeDiscountCodeSave": 0.0
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJpbmNvbWUiOnsiY3VycmVuY3kiOiJQTE4iLCJhbW91bnQiOjEwfSwib3V0Y29tZSI6eyJjdXJyZW5jeSI6IkVVUiIsImFtb3VudCI6Mi4zfSwidG9rZW4iOiIyYzJhNGExZTBhZDFlYjFlOTg3YzVjZjI0ODYxOGIwMDFlNjdhY2FiMjQwODE5MjdkNTg3Y2NkOTQxNWRjYjFjMDY4MjM0YWRmZjRlY2RjYjc3OWQ2ZGMwYTJlZTM3YjgyYzhiMWE4Y2I4OTc4ZjI0OTc2YWQ0N2EwZjQ3MWE1YyIsImV4cGlyYXRpb25EYXRlIjoiMjAyMy0xMi0xMSAxMzoxNjo0MyIsInZhbGlkRGlzY291bnRDb2RlIjpmYWxzZSwicmF0ZVNjYWxpbmciOjEsImxpbWl0TmF0aXZlQW1vdW50RXhjZWVkZWQiOmZhbHNlLCJ0cmFuc2FjdGlvbkxpbWl0RXhjZWVkZWQiOmZhbHNlLCJuZWdvdGlhdGVSYXRlIjpmYWxzZSwicmF0ZVNlbGwiOjEuMCwicmF0ZUJ1eSI6NC4zNDg0LCJoYXNQZW5kaW5nVHJhbnNhY3Rpb25zIjp0cnVlLCJleGNoYW5nZVJhdGUiOjQuMzQ4NCwiZXhjaGFuZ2VSYXRlV2l0aG91dENvZGUiOjQuMzQ4NCwiZXhjaGFuZ2VEaXNjb3VudENvZGVTYXZlIjowLjB9.h82OL-ojNFv-WC-0Dh0JB6nrkq0jINn43OK9VtO-l9FjWvqBmI131L-I43-SdrXm77M0NRKoRzPHL7a5VrZjQsrLzgzoKIeV_HuMCZifHglTHpQaGR_oWH2RfgJD2ls4doU1sJHpQ3Jxu0O6LBdh8eYdxxTMD63hO_U-wJl_K8_Ol0gQJwuldnSw0ENs1l_JSXWehlcWQ93bEqxqyNIhvBwEwYXe1FQiasWloQGeaPeOFNcinDI-a1vabJYjg3QwZefqBeNJ_PsaxPehJ-PFcI4iibJFISnqfawArI31nK5QM78iz6c4l_Z-UXgZ28vRqWgtpXLBgF7SwXUAXrGLXw

Prepare currency exchange order. The order is created in the draft status. The order is valid for 15 seconds. After this time, the order will be canceled. In the confirmation process should be used POST /v1/currency_exchange/transactions/confirm method.

Resource

POST <CONOTOXIA_HOST>/v1/currency_exchange/transactions

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Request object

Field name Type Required Limit Description
title string NO 128 characters Title of outcome bank transfer
discountCode string NO max. 20 characters Discount code
purpose string NO max. 128 characters Purpose of currency exchange
natureOfPayment string NO 12 characters Nature of payment code according to ISO 20022. Allowed nature of payment codes are defined in the List of supported nature of payment codes
from object YES
from.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
from.value decimal YES max. 20 characters Amount what you want to sell. Required when you are selling the currency
from.account number NO 14 digits Unique identifier of the account bank. Required when type is account
from.type string YES max. 6 characters Type of exchange (WALLET or IBAN)
to object YES
to.amount.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
to.amount.value decimal YES max. 20 characters Amount what you want to buy. Required when you are buying the currency
to.account number NO 14 digits Unique identifier of the account bank. Required when type is account
to.type string YES max. 6 characters Type of exchange (WALLET or IBAN)

Response object

Field name Type Required Limit Description
token string YES 128 characters Unique token to confirm created draft of currency exchange
expirationDate string YES 20 characters Expiration date of token in UTC format. Example: 2024-02-05T12:03:42.000Z
validDiscountCode boolean YES Sent discount code is valid
rateScaling integer YES max. 4 characters Rate scaling of currency exchange. Example: 100 is rate per 100 units
limitNativeAmountExceeded boolean YES Amount limit for waiting currency exchange exceeded
transactionLimitExceeded boolean YES Count limit for currency exchange exceeded
negotiateRate boolean YES Negotiated rate used
rateSell rate YES Partialy currency exchange rate
rateBuy rate YES Partialy currency exchange rate
hasPendingTransactions boolean YES Have a panding transaction to pay
exchangeRate rate YES Finally currency exchange rate
exchangeRateWithoutCode rate YES Rate without using discount code
exchangeDiscountCodeSave decimal YES Saved amount by discount code
from object YES
from.amount.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
from.amount.value decimal YES max. 20 characters Amount what you want to sell. Required when you are selling currency
to object YES
to.amount.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
to.amount.value decimal YES max. 20 characters Amount what you want to buy. Required when you are buying currency

API errors

The POST /v1/currency_exchange/transactions method can only return technical errors.

Confirm currency exchange

curl -X GET
    -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM"
    "<CONOTOXIA_HOST>/v1/currency_exchange/transactions/confirm

Request headers:

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

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

Request body:

{
    "token":"5faf392757db668aff4fc13a784bb79a6b7209eedc0583153230b247297c669b25ecf0bc9eb05d7eedc8ba291ade57747b7efe0a793addb74b71307bd7f3a3bd"
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Il8yNzVUd3dYOVhtaVotak1wLTJwNDZ0SUsyZE0tR2xWM3dYTU1GUTM5UUEifQ.ewogICAiZGF0YSI6WwogICAgICB7CiAgICAgICAgICJwYXltZW50SWQiOiJQQVk3NzIyMzc2OTI1NDgxMTciLAogICAgICAgICAiZXh0ZXJuYWxQYXltZW50SWQiOiIxMjgvMDYvMjAxOCIsCiAgICAgICAgICJzdGF0dXMiOiJQUk9DRVNTSU5HIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjE1My4xMywKICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICB9LAogICAgICAgICAiZGVzY3JpcHRpb24iOiJPcmRlciAwMDAwMDAwMDEiLAogICAgICAgICAicGFydG5lciI6ewogICAgICAgICAgICAiY29tbWlzc2lvbiI6ewogICAgICAgICAgICAgICAiZmVlIjp7CiAgICAgICAgICAgICAgICAgICJ2YWx1ZSI6MS4yNSwKICAgICAgICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICAgfSwKICAgICAgICAgInR5cGUiOiJPTkxJTkVfUEFZTUVOVCIsCiAgICAgICAgICJjcmVhdGVkRGF0ZSI6IjIwMjEtMDItMTdUMTE6MzY6MTUuMzY3WiIKICAgICAgfSwKICAgICAgewogICAgICAgICAicGF5bWVudElkIjoiUEFZODE1NTc2NTc2NzQxMzkxIiwKICAgICAgICAgImV4dGVybmFsUGF5bWVudElkIjoiMTIxLzA2LzIwMTgiLAogICAgICAgICAic3RhdHVzIjoiQk9PS0VEIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjIzLjUyLAogICAgICAgICAgICAiY3VycmVuY3kiOiJFVVIiCiAgICAgICAgIH0sCiAgICAgICAgICJkZXNjcmlwdGlvbiI6Ik9yZGVyIDAwMDAwMDAwMiIsCiAgICAgICAgICJ0eXBlIjoiT05MSU5FX1BBWU1FTlQiLAogICAgICAgICAiY3JlYXRlZERhdGUiOiIyMDIxLTAxLTExVDA3OjI2OjMzLjMwMloiLAogICAgICAgICAiYm9va2VkRGF0ZSI6IjIwMjEtMDEtMTFUMDc6Mjk6MzYuNDY4WiIKICAgICAgfQogICBdLAogICAicGFnaW5hdGlvbiI6ewogICAgICAiZmlyc3QiOnRydWUsCiAgICAgICJsYXN0Ijp0cnVlLAogICAgICAiY3VycmVudFBhZ2VOdW1iZXIiOjEsCiAgICAgICJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsCiAgICAgICJwYWdlU2l6ZSI6MTAsCiAgICAgICJ0b3RhbFBhZ2VzIjoxLAogICAgICAidG90YWxFbGVtZW50cyI6MiwKICAgICAgInBhZ2VMaW1pdEV4Y2VlZGVkIjp0cnVlCiAgIH0KfQ.EuuDkfr9rv90nlZ0hbjTGa014qw_oB8EDTy1DEwfpgeFuEOK7yeEJztPX07jhT3pwdIB7Dc8c9sbSCgKMCvIjoXReNicw6LyJxQwyTs9tR8BEF-UWoLKxSqUP1h_T4jpPw9YH8GMGa1UZI9nktICNezbz35fAk5UH5RhMtIbvrpxVyz4AgBGv5oxqOOS2tXj1vIjZnJ8Vu46LkLKhUZ7RyHjJxUrf5UjkghwMY4URqkKD7jX7-YENfNy5tnH1kfyvtn1osxRfjDGY1wX4JbFUlVFJdkHed0WhcEIIoqYf4MUZ6yD5XvUu1784V3Gq2VVmvoVZiawAU-nUZtbmskr4w

Response headers:

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

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

Response body:

{
    "id": 981449842427
}

eyJhbGciOiJSUzI1NiIsImtpZCI6Il8yNzVUd3dYOVhtaVotak1wLTJwNDZ0SUsyZE0tR2xWM3dYTU1GUTM5UUEifQ.ewogICAiZGF0YSI6WwogICAgICB7CiAgICAgICAgICJwYXltZW50SWQiOiJQQVk3NzIyMzc2OTI1NDgxMTciLAogICAgICAgICAiZXh0ZXJuYWxQYXltZW50SWQiOiIxMjgvMDYvMjAxOCIsCiAgICAgICAgICJzdGF0dXMiOiJQUk9DRVNTSU5HIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjE1My4xMywKICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICB9LAogICAgICAgICAiZGVzY3JpcHRpb24iOiJPcmRlciAwMDAwMDAwMDEiLAogICAgICAgICAicGFydG5lciI6ewogICAgICAgICAgICAiY29tbWlzc2lvbiI6ewogICAgICAgICAgICAgICAiZmVlIjp7CiAgICAgICAgICAgICAgICAgICJ2YWx1ZSI6MS4yNSwKICAgICAgICAgICAgICAgICAgImN1cnJlbmN5IjoiRVVSIgogICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICAgfSwKICAgICAgICAgInR5cGUiOiJPTkxJTkVfUEFZTUVOVCIsCiAgICAgICAgICJjcmVhdGVkRGF0ZSI6IjIwMjEtMDItMTdUMTE6MzY6MTUuMzY3WiIKICAgICAgfSwKICAgICAgewogICAgICAgICAicGF5bWVudElkIjoiUEFZODE1NTc2NTc2NzQxMzkxIiwKICAgICAgICAgImV4dGVybmFsUGF5bWVudElkIjoiMTIxLzA2LzIwMTgiLAogICAgICAgICAic3RhdHVzIjoiQk9PS0VEIiwKICAgICAgICAgImFtb3VudCI6ewogICAgICAgICAgICAidmFsdWUiOjIzLjUyLAogICAgICAgICAgICAiY3VycmVuY3kiOiJFVVIiCiAgICAgICAgIH0sCiAgICAgICAgICJkZXNjcmlwdGlvbiI6Ik9yZGVyIDAwMDAwMDAwMiIsCiAgICAgICAgICJ0eXBlIjoiT05MSU5FX1BBWU1FTlQiLAogICAgICAgICAiY3JlYXRlZERhdGUiOiIyMDIxLTAxLTExVDA3OjI2OjMzLjMwMloiLAogICAgICAgICAiYm9va2VkRGF0ZSI6IjIwMjEtMDEtMTFUMDc6Mjk6MzYuNDY4WiIKICAgICAgfQogICBdLAogICAicGFnaW5hdGlvbiI6ewogICAgICAiZmlyc3QiOnRydWUsCiAgICAgICJsYXN0Ijp0cnVlLAogICAgICAiY3VycmVudFBhZ2VOdW1iZXIiOjEsCiAgICAgICJjdXJyZW50UGFnZUVsZW1lbnRzQ291bnQiOjIsCiAgICAgICJwYWdlU2l6ZSI6MTAsCiAgICAgICJ0b3RhbFBhZ2VzIjoxLAogICAgICAidG90YWxFbGVtZW50cyI6MiwKICAgICAgInBhZ2VMaW1pdEV4Y2VlZGVkIjp0cnVlCiAgIH0KfQ.EuuDkfr9rv90nlZ0hbjTGa014qw_oB8EDTy1DEwfpgeFuEOK7yeEJztPX07jhT3pwdIB7Dc8c9sbSCgKMCvIjoXReNicw6LyJxQwyTs9tR8BEF-UWoLKxSqUP1h_T4jpPw9YH8GMGa1UZI9nktICNezbz35fAk5UH5RhMtIbvrpxVyz4AgBGv5oxqOOS2tXj1vIjZnJ8Vu46LkLKhUZ7RyHjJxUrf5UjkghwMY4URqkKD7jX7-YENfNy5tnH1kfyvtn1osxRfjDGY1wX4JbFUlVFJdkHed0WhcEIIoqYf4MUZ6yD5XvUu1784V3Gq2VVmvoVZiawAU-nUZtbmskr4w

Confirm currency exchange transaction by token.

Resource

POST <CONOTOXIA_HOST>/v1/currency_exchange/transactions/confirm

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Request object

Field name Type Required Limit Description
token string YES 128 characters Unique token to confirm created draft of currency exchange

Response object

Field name Type Required Limit Description
id number YES 12 digits Unique currency exchange transction ID number

API errors

The POST /v1/currency_exchange/transaction/confirm method can only return technical errors.

Receiving details of currency exchange transaction

curl -X GET
    -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM"
    "<CONOTOXIA_HOST>/v1/currency_exchange/transactions/{transactionId}

Response headers:

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

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

Response body:

{
  "id": 938517970189,
  "from": {
    "amount": {
      "value": 10,
      "currency": "PLN"
    },
  },
  "to": {
    "amount": {
      "value": 2.3,
      "currency": "EUR"
    }
  },
  "rate": 4.3493,
  "rateScaling": 1,
  "created": "2024-02-05T12:03:42.000Z",
  "status": "REALIZED",
  "paymentMethod": "CURRENCY_WALLET",
  "recipient": {
    "account": "27114018505111398559981609",
    "bank": "mBANK"
  },
  "isTransferData": false
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJpZCI6OTM4NTE3OTcwMTg5LCJpbmNvbWUiOnsiYW1vdW50IjoxMCwiY3VycmVuY3kiOiJQTE4ifSwib3V0Y29tZSI6eyJhbW91bnQiOjIuMywiY3VycmVuY3kiOiJFVVIifSwicmF0ZSI6NC4zNDkzLCJyYXRlU2NhbGluZyI6MSwiY3JlYXRlZCI6IjIwMjQtMDItMDVUMTI6MDM6NDIuMDAwWiIsInN0YXR1cyI6IlJFQUxJWkVEIiwicGF5bWVudE1ldGhvZCI6IkNVUlJFTkNZX1dBTExFVCIsInJlY2lwaWVudCI6eyJhY2NvdW50IjoiMjcxMTQwMTg1MDUxMTEzOTg1NTk5ODE2MDkiLCJiYW5rIjoibUJBTksifSwiaXNUcmFuc2ZlckRhdGEiOmZhbHNlfQ.MvOKY8hHkB7pjWqpZR5nmC5KEc_G5W58ngsiV9SLq2dqJG0IjMNz6P_X1rl4aChVZScx7yj7xZTxI3h2GZcfQo33bEuXTy8uYlya2s8OnOI4akxo0SGmgCiuMRAJr5swnGTYGdXLyVuj1foyzu83Tu_iXmgS696cZhNI3w-pW5znyRTO_NhhtShQtdWH7ZbeXPVzAs5s_LtPKcMXGLfG0_XDgn-LIoSo_PEvyFTSgoz9AIWCO5FaKdh-4bR-cIByDDXgai9CnCtMNZg_1EEr-iK2C-u51CxpbouCIVpv09PWx1hgiVDOzOsR9WmZpijygLBmbOy3ni1Cqj0POuCCng

Gets a details of currency exchange transaction.

Resource

GET <CONOTOXIA_PAY_HOST>/v1/currency_exchange/transactions/{transactionId}

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Response object containing currency exchange transaction status

Field name Type Required Limit Description
id Number YES 12 digits Unique currency exchange transction ID number
from object YES
from.amount.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
from.amount.value decimal YES max. 20 characters Amount what you want to sell. Required when you are selling the currency
discount NO Discount details
discount.amount decimal NO max. 20 characters Discount amount
discount.currency string NO 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
discount.rate decimal NO max. 20 characters Discount rate
to object YES
to.amount.currency string YES 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies
to.amount.value decimal YES max. 20 characters Amount what you want to buy. Required when you are buying the currency
fees array NO Array of fees
rate rate YES Currency exchange rate
rateScaling integer YES max. 4 characters Rate scaling of currency exchange. Example: 100 is rate per 100 units
created string YES 20 characters Date and time of currency exchange transaction creation in UTC format. Example: 2024-02-05T12:03:42.000Z
status String YES max. 20 elements Status name of created transaction, see Statuses.
paymentMethod String YES max. 20 elements Payment method used for currency exchange transaction (BANK_ACCOUNT or CURRENCY_WALLET)
recipient object NO Recipient bank account details
recipient.account string NO max. 26 characters Recipient bank account number
recipient.bank string NO max. 20 characters Recipient bank name
recipient.routingNumber string NO max. 10 characters Recipient bank routing number (only USA accounts)
transferData array NO Array of transfer data to pay exchange currency
transferData[].key string NO max. 50 characters Key of transfer data
transferData[].value string NO max. 50 characters Value of transfer data
transferData[].currency string NO 3 characters Currency code according to ISO 4217. Allowed currency codes are defined in the List of supported currencies

API errors

The GET /v1/currency_exchange/transactions/{transactionId} method can only return technical errors.

Dictionaries

Transaction status

Status Description
WAITING
IN_PROGRESS
SUCCESS
SUSPEND
VERIFICATION
CANCEL

Currency

Currency Currency code Number of digits after the decimal separator Minimum currency units for a transaction
Dirham (United Arab Emirates) AED 2 1
Australian dollar AUD 2 1
Bulgarian lev BGN 2 1
Canadaian Dollar CAD 2 1
Swiss franc CHF 2 1
Chinese yuan CNY 2 1
Czech Republic Koruna CZK 2 10
Denmark Krone DKK 2 10
Euro EUR 2 1
Bristish pound GBP 2 1
Hong Kong dollar HKD 2 1
Hungarian forint HUF 0 100
Israeli new shekel ILS 2 1
Japanese yen JPY 0 100
Mexico Peso MXN 2 1
Norwegian krone NOK 2 10
New Zealand dollar NZD 2 1
Polish zloty PLN 2 1
Romanian leu RON 2 1
Swedish krone SEK 2 10
Singapore dollar SGD 2 1
Turkish lira TRY 2 1
United States dollar USD 2 1
South Africa rand ZAR 2 1
Thailand baht THB 2 100
Serbian dinar RSD 2 10

Nature of payment

Nature of payment is required for currency exchange where outcome currency is CNY.

Nature of payment Description
CCTFDR Cross border capital
CGODDR Goods trade
CSTRDR Service trade
COCADR Other currency account transactions

API errors - technical

Description of errors returned by Conotoxia Pay API for all shared resources.

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkJhZCBSZXF1ZXN0Iiwic3RhdHVzIjo0MDAsImRldGFpbCI6IlVuZXhwZWN0ZWQgY2hhcmFjdGVyICgnZicgKGNvZGUgMTAyKSk6IHdhcyBleHBlY3RpbmcgY29tbWEgdG8gc2VwYXJhdGUgT2JqZWN0IGVudHJpZXMifQ.Ou8rJviQ9T2Ebj9Q7Wwza0T4G6EIFBRbWCIuEX8bBjVwW8OL_hvqYYC_4lbAMkp2Si6rlzp373Pj4wlkxxX0hkub91wsMDDUHDkEysOXJY9jOGoUOgHmZTP7JrvGdEZcN8DtUulTn55s_rNxSO66-IKYoOOcFwEAL_0zJ4aDb8mXdcY_gmgLyVnq4EKJL2lBai88UG63mRayWiiIWR5I-UFvsQ8X0wRSrEzJwzz7zOl-DeKoku5dZTIwqtPOksy4BMJXDFLlcDg5MvIFa40yO1M8Hn8SN2bxMCCgo3NkzXC4RZ3lgAHyyvpLdHsJdfiU1iqz8YhgeV1MuxqaJ-sCEQ

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

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkZvcmJpZGRlbiIsInN0YXR1cyI6NDAzfQ.Wwp9fE54f3KclIVvGVdU3ZpUGZ4qZtC4PTyLXyAJRdqlDTcyDjIJ1ccGVKLv1YYdd_TZewiVqMR_iKCMeAoKlrFq8qsPH8NRXfJ4LCOopfF9i9zdfLkNXIVJkqm_1H-qsU9AvorPSB1mqNKy4MYfj5k-KWN559yFagBL4P2shwR3Ee0_cDy8A11fbR_8jzs5nU-hWOFR5qME7QG7leEM9ZRuna2ogRShEhXMqbThRnbDLU73uVWPmlj_5hJ8FBDjl_v5KrUBOKDFp2Hdq1t9sjzqvJPzuKYr_J6rWLa3FTlOv6ew4RuvWDgUTCJW_xaQMKSC181OgtSuYcUlH7XISg

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6Ik1ldGhvZCBOb3QgQWxsb3dlZCIsInN0YXR1cyI6NDA1LCJkZXRhaWwiOiJSZXF1ZXN0IG1ldGhvZCAnUFVUJyBub3Qgc3VwcG9ydGVkIn0.HScFAydfT_EHZwvbkT_izwBUAlb3CCt_X6nhs_XQxkHrbpQL1hDg5JrcxYGsC5O14yXgnwUMxKlc7YO66X1j9CZAbRxL5Hi95NKMJZuh0BM1geweQYGvBbrRrd6GylK-4Me5Nllr-nJkry1h7yPlYrbVo1KBVA6gT88j9yJuWhr7OWfW0-2LbQlHEwYvhr9Df0b6Yr1noqOV7Wb7sO8yvqSi9S5oCqVbsFPqRr8Pz7H41m7qcVKM9sTUlN82F5AFMI-jk6gqu3zcvJPdXcQNmLVn7nVXIItfPfvr0wyGCKHECq--d5bhBjL-1ARUv4rz8A0FgsINqTyz25JqHwQ_YA

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

409 Conflict

Response headers:

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

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

Response body:

{
    "title": "Conflict",
    "status": 409,
    "detail": "Currency from payload is different than the currency from products"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkNvbmZsaWN0Iiwic3RhdHVzIjo0MDksImRldGFpbCI6IkN1cnJlbmN5IGZyb20gcGF5bWVudERhdGEudG90YWxBbW91bnQgaXMgZGlmZmVyZW50IHRoYW4gdGhlIGN1cnJlbmN5IGZyb20gcHJvZHVjdHMifQ.I9UnyltseJc-47VPDzwrRQ-i1rL1Y_y6mNAI7BEOEgkQ2rH8cKGE1oTeNI0wqbVaTCXYiCE95wDVFHJz4UGbwZWthMpHEt6IGcPj-OrxDREDnRgTPfyIRkTLIbud8BSHaQvdpSgJBneGe5BSIRDeu0Mo9h9ATo0b5lltQq_R4bb9zpAni6xQ2oO-XI2blPx2A2OvHr89D96gdMVUa6pWI_HIzixDsUMTXbDwO0DlC6jCLMv81_v4VWZuUMQ9dmiP0PsnodOKLZkxKc03X5Ymnfz6nrMdqZKiWdBK7StwReucW38itcxWsiKyZ3oMYzFKYWUdWQNH3pGoghzBZcbGNg

Returned when business validation errors occur.

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IlVuc3VwcG9ydGVkIE1lZGlhIFR5cGUiLCJzdGF0dXMiOjQxNSwiZGV0YWlsIjoiQ29udGVudCB0eXBlICdhcHBsaWNhdGlvbi94LXd3dy1mb3JtLXVybGVuY29kZWQnIG5vdCBzdXBwb3J0ZWQifQ.Q7ri8IKmShewu9w2jNCZykGyP51lX-DoExwEbrcjwMjXrIwFRhiVNALRMySwULfoTOnIfk9fq7Je5Txuv-ftM-JSJ0Dif_rrRfcLigRUm0XBPzKLAl675uG4pRSvj5ZtJ9g98ti_zLbarSiYTjwouGqgKmsfz_K9ZwdNM8NCnB3X7G9z0CKchYRtFemprULYRYxBVymFr6on9mkeNsPc72q9TeQB0hXVmLTaNVGro_0yae7_avL0AOjKwY5AXrxCBRxuyhcYsSl_i2PJF5mGbitZFoPNidL16eL4xovVA-mMcuOKldEUpFilvAOCHrbCggAr3BQpauZVyiokRqi5Fw

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IkludGVybmFsIFNlcnZlciBFcnJvciIsInN0YXR1cyI6NTAwfQ.Lm349V3_rGQ-iW0YnARC6BZxhP8duh2NurOR_fyEtOp4EIc70PGupAr_A81gerc85ixEtS3Ux0DVZPxWIjbA8l9VyUk48fhpLPvC6hYk5b79fZ4YmHtkDdICpP0OT9YKeZhx3Htrhmn7BsP-cFLNudV_shod0GtGHa-ONBx56J4iV37EzQH4atThkusHiRW4p8NzuwRch9I-hnS26aR3KhDmiWQl0xsKDYrPnOu3-45vufpfl4qZ0gPDhsKGgsts9zVI1GONskf5-GJSLYLRstq39dxNGv_ZLRQ3IU1kxQHW4S1CmN8fbchxeA619WCh9NUdZOacu3jTXpBZlICX9w

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0aXRsZSI6IlNlcnZpY2UgVW5hdmFpbGFibGUiLCJzdGF0dXMiOjUwM30.C2_7xbFp0VJu141nO0fr5cUHKOipLic6XzY7_7Jqu0G8UkyjdCq4W8spggDsLIycfoDpzeJYuGkuIEJEK6Rh2phPiCBaphDHYmTYJPhy3lTPlxElIPya4Ml8WCr9Hf3-zec5NlOzCZDJRUcysjQOo4eI15LB--0YU2Fo4au7metxuZ83N71j0o-DJha083Em3VnmWNH4QE92983EUYPnEP0Y2jBjI-cEEZHgGe1ADzon7wrY60WIOKvvZ2WlDiWb_-cs6aLtLcNYAs5Fw1IB9L6OlCKuTmWM0OFwpeTvpQUCt1UGT4GGZw2rYBsgxsSvyUJOPdyskrFrIzmK7ypJsA

Service is not available.

API errors - business

Description of errors returned by Conotoxia Pay API, which type is defined by the type key.

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1qd3MiLCJzdGF0dXMiOjQwMCwidGl0bGUiOiJJbnZhbGlkIEpXUyIsInZhbGlkYXRpb24tZXJyb3JzIjpbeyJtZXNzYWdlIjoiSGVhZGVyICdraWQnIGlzIG1pc3NpbmciLCJtZXNzYWdlLWtleSI6IktpZEhlYWRlck1pc3NpbmciLCJjb250ZXh0LWtleSI6Imp3cyJ9XX0.ZiOPshS9m_DC_ZqKC-PZ-1EdCKcMXTtkuBzhTuCMKRBBLEMZ2B2e5kWxA2b8MLHrGOVeHfbePqFBozf9jLnoP7b0l_zSUrVcaMBvODwQ_jKjBai1GRH6vRDS16NHSFfnup0HTu2mX5RWF21FfFpoO3DDOGx17ngKPSte_5j1O3t-iZGvmZoxG1VDH3WCXmp0dPBmuq23Orsda-1hNcvM2Olz9sFFK7jQDWA9H-Pf0Su1XJrC9QnQCeHojlQZ0MsGAv0lQc59Pl7qUYgNCu3hIT7DwHvdaQwR2DETroEJuV7n4b6SiP5TLHbi94C7kMEwCB-T9WtERTsTojD4id0jPg

Returned when the format of the JWS request is incorrect:

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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1wZW0iLCJzdGF0dXMiOjQwMCwidGl0bGUiOiJDYW4gbm90IHJlYWQgcHVibGljIGtleSBmcm9tIFBFTSIsImRldGFpbCI6IkNhbiBub3QgcmVhZCBwdWJsaWMga2V5IGZyb20gUEVNIn0.gD_vJFnDZOP3TyWrT7qZcTMlMMq4oExAsglE6gKwjmXdawHTYSatavxBW3Xw6P5w8JPCtyS_JtERg5gLPfrZiu3wfgxC27cLN33kIyfT4HH4OpuNTSpQyhmf7zYksIfXSsUFsFLX_FbFK9-hLbH8iUj6ryJOUj4hXHxSAUPtl45z5yqRyWADC_wQDmYzuoSW_ULzTEBYnQkt63950AODXtJHxDskaMIYFfzKoWIPiSRDdluPfTALua4iN8rKqNL9RSaMHx0UKX3wTJk1qaQDicpVkXvTydpgX5hnXwaPsd38lSSyMh1CR0Vn5aZmLssO21kwKhuyacmHOwU6imljdQ

Returned when the public key sent 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

Response body:

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoiaW52YWxpZC1wdWJsaWMta2V5Iiwic3RhdHVzIjo0MDAsInRpdGxlIjoiSW52YWxpZCBwdWJsaWMga2V5IiwiZGV0YWlsIjoiSW52YWxpZCBwdWJsaWMga2V5In0.SIWrgXX6OuvFsjH-10ON59jO1X6SJrBKzyyJj0Qp_sN4tkHn2kP8PXKvIBJkxwyfAKvTtOinq5PwivEHP8oyVm_JpMUtgkGRHGzU91LGzn-SnbqT5oydzfBwQWgHevvgZ3bGeSo72F2L3Ahaq0UmtID9G-mx8otoW6iU2JArhV-0LfZn1bwzxJydiLie7AFBMi4ekJ6ksewL5RPZRgPEs_BR-sPapbym4eL51vr70n8Vbe3O_PJcEbrYml0yx4BXqdDI_0NDsU7JoV6aekOyoU_9s0PjRqtKqa-Oz5C-wyXwtr-4mIy23AtEZMi8AS0loWnoFpPbX7T4E6PM1PMC2A

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

Response body:

{
    "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"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoic2FtcGxlLXRleHQtc2lnbmF0dXJlLW5vdC1tYXRjaCIsInN0YXR1cyI6NDAwLCJ0aXRsZSI6IlNhbXBsZSB0ZXh0IHNpZ25hdHVyZSBub3QgbWF0Y2giLCJkZXRhaWwiOiJTYW1wbGUgZGVjb2RlZCB0ZXh0IG11c3QgaGF2ZSBzaWduZWQgd2l0aCBTSEEtMjU2IHNpZ25hdHVyZSJ9.aBsf1MOmQc4eadXoaBQG7Pj2klmwNUfC1CFbBYc_1-krZOIXhBBff6lLa9ozDEqQeVh1CEnNPQ_ZxQzsfNYK4-wUIiE1F1ar1B29YQdb7YFqw9vAct3t8Tc5SfMO7LrbkpG6gSI1ox6tUFL9g6atwOwZF33kkPME4n5pKyxbBL2fK5hElcOqITJrmJnMxmZAOYPkgoj_dwtuK7PDREKO_E9YdXF8GBibCJnTJFnovXdfLIYfM4NS3pSgWUHFysLZS9Y4RxLJff9rGfXhX0i3KjxbLFhHgn_tBrKfgfCd7ysAb2aTMqAba15ULNPBNjRG8k4B-zpKGbVRRlSF5BFDhg

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

Response body:

{
    "type": "validation-error",
    "title": "Request parameters are not valid",
    "status": 400,
    "validation-errors": [
        {
        "context-key": "to.type",
        "message": "Incorrect field value",
        "message-key": "incorrect-value"
        }
    ]
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJ0eXBlIjoidmFsaWRhdGlvbi1lcnJvciIsInRpdGxlIjoiUmVxdWVzdCBwYXJhbWV0ZXJzIGFyZSBub3QgdmFsaWQiLCJzdGF0dXMiOjQwMCwidmFsaWRhdGlvbi1lcnJvcnMiOlt7ImNvbnRleHQta2V5Ijoib3V0Y29tZSIsIm1lc3NhZ2UiOiJJbmNvcnJlY3QgZmllbGQgdmFsdWUiLCJtZXNzYWdlLWtleSI6ImluY29ycmVjdC12YWx1ZSJ9XX0.qDwwuqX5EVP5H1QSVAzAfRGc9ys1IPY1YFsoXaKu1H_BH6F4nGZ0n3GOZvi5y9aLwA9OSnkWBq0_p_pMtnJ4SeqrrmckZP49lRRMCQ3gXmSr4yuPS74Pvrfj-yEOAbH14znXw5NvXASzI5tgkdM0C_e09Fg6lQrVTjfx4R919VJO_byN0rkx50XhJZHATXy_983o9CSze4i9ue_JrQ-1bb_fFKz09LP3dl2_54yzjnUer00TS_xw3oITTebDQ1CL-S3IPDayoyI6IlUR81EKn-NsjNKbeo-TIReUK65DLheDrlUgGMAll5W4tUWLYTh7Qpv4YlddfQ58k2kD-V5HRw```

Returned when specified request parameters are incorrect.

unknown-exchange-flow

Response headers:

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

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

Response body:

{
    "type": "unknown-exchange-flow",
    "title": "Unknown exchange flow",
    "detail": "Unknown exchange flow given in request by type fields",
    "status": 400
}

Unknown exchange flow given in request by type fields. Alowed values are WALLET and IBAN on from.type and to.type.

unauthorized-access

Response headers:

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

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

Response body:

{
    "type": "unauthorized-access",
    "title": "Unauthorized access to this part of the system",
    "status": 403
}

The selected part of system is disabled or not available for the user.

payment-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

Response body:

{
    "type": "EME1",
    "status": 404,
    "detail": "Not Found."
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJzdGF0dXMiOiJSRUFMSVpFRCJ9.lpczwRP7ub39-VgK_bkhX5JwDJhfAJohtnMK_SxtjtpCZJdJK1BIl7BNBhy8cFyPtloi33McZ6WrpqwsZY28Hz918uvQ6KR-zFdcCNR9EY8IQhSR0XFbrZqETfWa53LAvr_ZSya_U_qtIn6ueQBdcZ3B8c6CoQmr6dfT4wtQJ_gYqkE-v-gBkI2FfABZmAKBXIJoyCiGfvxOd6g01ZNp1alGua0W-Umm4NDcsiPtIRcALZSYGBLOfS_3ju6-wUV1L0jjFEm0ULpShf6WAvqKL5ViZdjdQBzwqTQbZv20PI5ad7lMi5CPSbp8WlsVte32zmKVY3xHsslMdPkjCYGPkA```

The identifier of the shop linked to the point of sale is incorrect.

ambiguous-exchange-direction

Response headers:

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

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

Response body:

{
    "type": "ambiguous-exchange-direction",
    "title": "Ambiguous exchange direction",
    "details": "Please provide transaction direction by adding one amount value",
    "status": 409
}

Please provide transaction direction by filling out only one amount value. The transaction direction can be inferred from the amount (from or to) values provided in the request body.

create-currency-exchange-error

Response headers:

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

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

Response body:

{
    "type": "create-currency-exchange-error",
    "title": "Create currency exchange error",
    "detail": "An error occurred during the creation of the currency exchange",
    "status": 409
}

Unexpected error during the creation of the currency exchange transaction

incomplete-profile

Response headers:

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

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

Response body:

{
    "type": "incomplete-profile",
    "type": "Incomplete profile",
    "title": "The profile is incomplete, or the required consents have not been accepted",
    "status": 409
}

The profile is incomplete, or the required consents have not been accepted.

no-id-scan

Response headers:

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

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

Response body:

{
    "type": "no-id-scan",
    "title": "No ID scan",
    "detail": "Please enclose a scan of the ID. Please send a scan of the documents as an attachment to your profile",
    "status": 409
}

Please enclose a scan of the ID. Please send a scan of the documents as an attachment to your profile.

short-transaction-interval

Response headers:

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

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

Response body:

{
    "type": "short-transaction-interval",
    "title": "Too short transaction interval",
    "detail": "The time since the last transaction is too short. Please try again in a moment.",
    "status": 409
}

The time since the last transaction is too short. Please try again in a moment.

unavailable-currency-rate

Response headers:

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

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

Response body:

{
    "type": "unavailable-currency-rate",
    "title": "Unavailable currency rate",
    "detail": "The currency rate is currently unavailable",
    "status": 409
}

The currency rate is currently unavailable. This is a temporary error, and the customer should retry the request after a short time or use another currency pair.

public-key-already-revoked

Response headers:

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

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

Response body:

{
    "type": "public-key-already-revoked",
    "title": "Public key already revoked",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ already revoked"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1hbHJlYWR5LXJldm9rZWQiLCJ0aXRsZSI6IlB1YmxpYyBrZXkgYWxyZWFkeSByZXZva2VkIiwic3RhdHVzIjo0MDksImRldGFpbCI6IkNsaWVudCBwdWJsaWMga2V5IHdpdGgga2lkIGxwU29lblVTc3l4UHRabGtQM3RHTEg5aVBMWm4xTDR6ZjBHOWpVaFgzelEgYWxyZWFkeSByZXZva2VkIn0.b8ynD7Vp2ShxJf6O2LAgat5JhEa-mdk7t0bHxCnWCG2RBkdo2LGPjogKWk850X9RBAHzCISOHgOiRu8zOKJKd5DlblgJeYSWhvpYXnt2H0vNUXkMst10MaWm06K0KUAVHATrK9FR0aloqPqcTSeklLjyGrNu4sRG3G_dJWNYH_s_IUCwUH7fAK050sGwCxyybNHQ0rZ0O3sozxpMZaaF0tYc7nLgr6ZiyDeFIdd9eC6SyFGNcuzEFG1c4G9ZiYjiBwRMAwu75dmyN-cRM2nJvHMNJ16CK8C4fOcPwY2ZXrjutdBejDAjhiRuGcXXFcEA1ydAdX8oOhpJTKGw-21Y-A

Returned when the key used for verification has been revoked.

public-key-is-not-activated

Response headers:

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

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

Response body:

{
    "type": "public-key-is-not-activated",
    "title": "Public key is not activated",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ is not activated"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1pcy1ub3QtYWN0aXZhdGVkIiwidGl0bGUiOiJQdWJsaWMga2V5IGFscmVhZHkgaXMgbm90IGFjdGl2YXRlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJDbGllbnQgcHVibGljIGtleSB3aXRoIGtpZCBscFNvZW5VU3N5eFB0WmxrUDN0R0xIOWlQTFpuMUw0emYwRzlqVWhYM3pRIGlzIG5vdCBhY3RpdmF0ZWQifQ.Mb_Naf5LCuvvUpEmCU1nt4sCT9KFnPZcwl3Zq1fnT0Zu0vOOqyOGhAiYA69VxwkhZ170FHA3L6a_56qNx4sNjL9V2oIVs4zLg0HI6jjrqZUWdGEPUgQO3Iq35J1f_afKi4GVaSw3-q0L9eIGyBcumTB1948IR0pNzAGtuR_8ep7wO536lJLJwJod9auS-XEtHba4d0zxiGHy-bqLTZKSOH_xwqWHpUSN3ZI0pD2fiz9HT8rv4_tsE0du-O79ykVdFnG-kWiNowC5ZNBG6wdNRBDAWW2-RHmXVsPaanPEcZ5zhfM9Q7Rw-zDH_21hQ4XSwtf32xu15Y5Ipa03bB_37g

Returned when the key used for verification is not activated.

currency-exchange-limit-exceeded

Response headers:

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

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

Response body:

{
    "type": "currency-exchange-limit-exceeded",
    "title": "Currency exchange limit exceeded",
    "details": "Amount of currency exceeds the set limit value of the currency exchange",
    "status": 409
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJ0eXBlIjoiY3VycmVuY3ktZXhjaGFuZ2UtbGltaXQtZXhjZWVkZWQiLCJ0aXRsZSI6IkFtb3VudCBvZiBjdXJyZW5jeSBleGNlZWRzIHRoZSBzZXQgbGltaXQgdmFsdWUgb2YgdGhlIGN1cnJlbmN5IGV4Y2hhbmdlIiwic3RhdHVzIjo0MDl9.HZ9xrBOFou3a4PxcaM5UrNIYbLHXlQHVWiNrVN1enJhL15RRMtTCgiUYPqQFW4H70OQXmwHt28NSIKNoyks-YKFaC4PdTDBPLS0LkzAgboJ0lZY-3c6Kv0KtcYaI3j-tTimuCPQIPxNwyikouhK7CwQxFCPnIaDSnt4niWGDD5RUTBeuCsLQrUrxrWAPRkqoOxTEdGzksWGURRE2LwRTO4-2mdlHhqygPN_8Ahpyg8ov7kOMWRqFlEpyAjo2oO43HIH4ziffUXe52gNCoTDEM7z8G-OEd0PTj4pFFG7ncGK8THDofvJEKOsTvzUR2GkBuNXUplQ7Onu6BCs1mjYCbA

The limit value of the currency exchange is exceeded. The limit value is set in the currency exchange settings.

invalid-currency-pair

Response headers:

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

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

Response body:

{
    "type": "invalid-currency-pair",
    "title": "Invalid currency pair",
    "status": 400
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJ0eXBlIjoiaW52YWxpZC1jdXJyZW5jeS1wYWlyIiwidGl0bGUiOiJJbnZhbGlkIGN1cnJlbmN5IHBhaXIiLCJzdGF0dXMiOjQwMH0.Il3seY99xwPRfChXHDtcSSN7jHep5f0RdI06mwvc4ljjcrcw7WZXVzB3Cu5RBtNhNxRs4EhcyjzkYEny8NA3YNZS-uZtN3SlTIdJTytOtdsiC7HcGi6SRjKts2DFHE1k_2HkG0XRbEsIthJQ6nSGHXVUUXFOk_970FskCrSZXmhKxhrGlzAu4d3UHy5th5TFtmlxLJZ1zPQ3mm2EMSkV-4lrKJ1Nkmg9JNnn-D9evjdkgn6a21YnF3vQl0W8BAW438dceexEGop7MIv5L17f2O_kuvFTNWZJehKmziNcJnkDyNuZRzmE3hMqdbE_r-Fn1fEw_qsKzeHjOLhhdWIOuw

The currency pair is invalid.

sample-text-verification-failed

Response headers:

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

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

Response body:

{
    "type": "sample-text-verification-failed",
    "title": "Sample text verification failed",
    "status": 409,
    "detail": "Signed text from encodedText not equals to unsigned text from decodedText"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoic2FtcGxlLXRleHQtdmVyaWZpY2F0aW9uLWZhaWxlZCIsInRpdGxlIjoiU2FtcGxlIHRleHQgdmVyaWZpY2F0aW9uIGZhaWxlZCIsInN0YXR1cyI6NDA5LCJkZXRhaWwiOiJTaWduZWQgdGV4dCBmcm9tIGVuY29kZWRUZXh0IG5vdCBlcXVhbHMgdG8gdW5zaWduZWQgdGV4dCBmcm9tIGRlY29kZWRUZXh0In0.bC1YhfaC5dukeaCFlsB-2SdllMsiOOkMCCjDpfauLthRu3RS-Ri_Lv0EH0D8dcE_Jr9Kaz9yUZlyTvs_Tbqy8clFRQLFvHB0TpOed4zt96ViY27Q9BLMmJS5HrlLSoAh4KG3I3ZkOKDQhyW1GJgFg98TKRox3bC9-xTpBedLkFOuVEbZsvQ7H2L5P3NU8nCbcvhguKCykcGkB_Misl5h7G_yrXk_vOZOKZSvFumUP-qjpBvSatXB7Sr7y-ca68RBu2smlPv8iDYwD61uPrrZZ5LOZvqUjJQEOBEzzCq4A2jTbQEZPeOVPvz4hdqYbCYlJysh5xNK2AnMZk2fzJ-bqw

Returned when the signed message in the encodedText field does not match the value given in decodedText.

public-key-has-wrong-length

Response headers:

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

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

Response body:

{
    "type": "public-key-has-wrong-length",
    "title": "Public key has wrong bytes length",
    "status": 409,
    "detail": "Client public key must have a minimum of 2 048 bytes"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1oYXMtd3JvbmctbGVuZ3RoIiwidGl0bGUiOiJQdWJsaWMga2V5IGhhcyB3cm9uZyBieXRlcyBsZW5ndGgiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiQ2xpZW50IHB1YmxpYyBrZXkgbXVzdCBoYXZlIGEgbWluaW11bSBvZiAywqAwNDggYnl0ZXMifQ.Vn0oLx-dZFMNfAKuyPXNNOo8gy2L8_gYkb1TkBYitHkcvS_jnFBuOEbq7LX-ah16NDSKQVO_rm5TVNzAMUqqe5fusek2zV_R8rDccDHuHWlk217BVWvBr9C6_W4VjNqjtOExpf8r7W5ycnvMLomKwIb1h-2cJTzjpB2nMW-PGSgMot-N2lnlu5EuXMmZ0jZ2d2sDoAcI9y6yeRPPt6cmtZ-a_PxJ2LNG_BL1av8Sht8qR9o46j4cHInIVabN5CdehaD7YDqRGT6GdAMVE4vme1ZOoE4xqBIHpszFXoDwFITLByOWY84D1QWfqKDSDaKlF_i0dfF1f2G3uDnE8fCBUA

Returned when the added public key is under 2048 bytes.

public-key-already-exist

Response headers:

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

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

Response body:

{
    "type": "public-key-already-exist",
    "title": "Public key already exist",
    "status": 409,
    "detail": "Client public key with kid lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ already exist",
    "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ"
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJ6QzRqNEFjaGR6d0tYU19NcXNoNEFmd1Z5U3VHc0ZnZ09fMnh2NXR1c3prIn0.eyJ0eXBlIjoicHVibGljLWtleS1hbHJlYWR5LWV4aXN0IiwidGl0bGUiOiJQdWJsaWMga2V5IGFscmVhZHkgZXhpc3QiLCJzdGF0dXMiOjQwOSwiZGV0YWlsIjoiQ2xpZW50IHB1YmxpYyBrZXkgd2l0aCBraWQgbHBTb2VuVVNzeXhQdFpsa1AzdEdMSDlpUExabjFMNHpmMEc5alVoWDN6USBhbHJlYWR5IGV4aXN0Iiwia2lkIjoibHBTb2VuVVNzeXhQdFpsa1AzdEdMSDlpUExabjFMNHpmMEc5alVoWDN6USJ9.QxoW3-rftVjDcNOtreF9ttRLUriMat_xJzpRvM3vPf08TZDK5RHdR6idUti18dKzX78hmmHS-PWXRwT9maCREqZBguqJfzFGwyBs5ui5jKi4V_SsX8-irb8EB-EhznyXQ5FidrF75_Vc69u9HythdIrnj3OimAnmALVKs8uDvZ-m-dED3Ua3-lE1sBIWExJ5R7bzNkuvpIRpzkt5vrEfqmnAYjVkL1ceUBCBgiqPqdi38CoIL0YQFUBlESUGYmXggXXYQcETVlftiieS1D1CJvTlIL5TRUTNXmt98-uvQsNcIkpYwyrtwqCrCkJr4TUh8AwX0dHwW7ThGKk8W9MooA

The given public key has already existed.

expired-token

Response headers:

HTTP/1.1 410 Gone
Content-Type: application/problem+json

HTTP/1.1 410 Gone
Content-Type: application/jose+json

Response body:

{
    "type": "expired-token",
    "title": "Expired token",
    "detail": "Time to use token has expired or token is invalid",
    "status": 410
}

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJ0eXBlIjoiZXhwaXJlZC10b2tlbiIsInRpdGxlIjoiVGltZSB0byB1c2UgdG9rZW4gaGFzIGV4cGlyZWQgb3IgdG9rZW4gaXMgaW52YWxpZCIsInN0YXR1cyI6NDEwfQ.SVWfXVQUTFNuycvecPAmOQHmySffA2V8kfQV1ZBL6xEfmoehf3pAh0uy-en6Iw35WQv42Xqw64Q1m-u38YRNxW8aTziUPRWVCQIkUg88vShFtGLGS5mUKIFFaGw7VPzL-trXGhD1QOqFjWpcDnByYhfK65bBN_ch6f0eEenGXCu7jUnyUBmIpwTX4zB9NS7WHY5SQ-o5pj_mPbsj8FA31W7B5mvA1YyawijkOdU0rc4EA0sQ5lNgaCgvYD60aUMpBoB-ZLWL8NJ09wgLWewizXLTNtSPBxLBPsKrWEpAwjN8iMJcqT94X8GSC9c1H4b17dZDtFpnf2LusqsMrJI6yg

When confirming a currency exchange transaction, if the validity period of the token has expired or the token sent is invalid.

Security

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

- All communication takes place with the use of the HTTPS protocol

It is required to send an authorization token in the Authorization header 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 Pay section) - All messages sent from the Conotoxia Pay 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 Pay 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 Pay:

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

Header

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 being sent (it can be, e.g., XML or String), but Conotoxia Pay 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 (.).

JWS Header

{
    "alg": "RS256",
    "kid": "J9u-RVn6McOzHPNLCQCN8O1mD5VF-kB0SIBn3wAzqnk"
}

JWS Payload

{
    "from": {
        "amount": {
            "currency": "PLN",
            "value": 10,
        }
        "type": "WALLET"
    },
    "to": {
        "amount": {
            "currency": "EUR",
            "value": 0,
        }
        "type": "WALLET"
    }
}

Example of a payment order:

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

data.jws
eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

Response headers:

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

Response body:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJpbmNvbWUiOnsiY3VycmVuY3kiOiJQTE4iLCJhbW91bnQiOjEwfSwib3V0Y29tZSI6eyJjdXJyZW5jeSI6IkVVUiIsImFtb3VudCI6Mi4zfSwidG9rZW4iOiJmZTA1NTM3MGE2NmU0M2RjZjc2MmUwMjVlNmY4ZGZkZmM3NGRkZjE1N2M4MmMwMzEyY2FlYzIwMjAxOTJkYzNjZGVhMmUwN2I2ZjA2Mzc1ZjRkYzI2YmFlNTJhNjVlYTE2MjczMjRhZTFhM2IxZDEwNzZjOTRhNmNmMzk0ZjZjZCIsImV4cGlyYXRpb25EYXRlIjoiMjAyMy0xMi0xMiAxMzo1MDowNCIsInZhbGlkRGlzY291bnRDb2RlIjpmYWxzZSwicmF0ZVNjYWxpbmciOjEsImxpbWl0TmF0aXZlQW1vdW50RXhjZWVkZWQiOmZhbHNlLCJ0cmFuc2FjdGlvbkxpbWl0RXhjZWVkZWQiOmZhbHNlLCJuZWdvdGlhdGVSYXRlIjpmYWxzZSwicmF0ZVNlbGwiOjEsInJhdGVCdXkiOjQuMzUxNCwiaGFzUGVuZGluZ1RyYW5zYWN0aW9ucyI6dHJ1ZSwiZXhjaGFuZ2VSYXRlIjo0LjM1MTQsImV4Y2hhbmdlUmF0ZVdpdGhvdXRDb2RlIjo0LjM1MTQsImV4Y2hhbmdlRGlzY291bnRDb2RlU2F2ZSI6MH0.GOLS7bl2YwPce7TosB8YQeoxLBwLdBEjI0DNFF7hDsoU5V3NAHf6tgsLhXb2O9OKeYDeBfKzXDvOKxiUWi8ktuSs4TqtsneDD64DN531BrMc1dPe3iUtx-83k7kQjCkVj_X89DqwOv8Xn3hQwBrt76qu2q-bmAeQjOxAjSUvqtp1j2J7CGAAzAH0HhmmxLk6_GKvmpwdXNl5zxT7MAw1SY1TNE9nHHJ66E1xsu6Yewy_rmcnsxC6f1fb_evVeYO97mJQ4yRYk_oW5CLJ_UkuxB3E9wqnoy4ovjxjjkISx8mgFJZ0TQdkXlEd84CBPilhEZhSHKE9au9VU9L_cez6hg

All messages sent from the Partner's system to the Conotoxia Pay 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 Pay:

eyJraWQiOiJERkRPbEI3RFU2LTBoUllBNVV1NEJiVEctcXJlY3NLdEJIU3kzVGppSXM4IiwiY3R5IjoiYXBwbGljYXRpb24vanNvbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.ew0KICAiZGVzY3JpcHRpb24iOiAiUGF5bWVudCBkZXNjcmlwdGlvbiIsDQogICJleHRlcm5hbFBheW1lbnRJZCI6ICIzNDJISEg4OExLREo4OTg3Njc2NyIsDQogICJjYXRlZ29yeSI6ICJFX0NPTU1FUkNFIiwNCiAgInBvaW50T2ZTYWxlSWQiOiAiUE9TNDU4OTYzMjE1OTY1NDc4NTkiLA0KICAidG90YWxBbW91bnQiOiB7DQogICAgImN1cnJlbmN5IjogIlVTRCIsDQogICAgInZhbHVlIjogMTkuOTkNCiAgfQ0KfQ.J2uDZEZL_hlgLAscv3EMX8lKCPBOf1X3UoUEDGhBF0cKFSAvHaDAAtnyzacL53RWsaHmAfDTRHqqFuF6g6wBRStbWukC1pOqXNEYHTXgfHJ01Sh7JZr7IRuX92ol-OgiP7DK01wDnlZ80_wGnJUpWGQjiQEoUzJhOcFyZ44_jSKh7dwU7SWh9wj5FWmC1A8RlBXLpMf6QWCKlA1njw4r7RXUmbLLbdiA71Oiy1LN_Ezf8srYP5y_QhhtoyXxkLEe75YP5ky6d0UObrKpUVbhvj7lwnqMzZVBfD1aIL5F2s8gUg8nQeCUWPUYIRvDNQkmAFTSbqjD2sCG1ysm8JDspA

After decoding JWS, a JWS Header and JWS Payload containing the minimum PaymentData 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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAupb2r8lA2zwgi95cR2CA
4CM6zYlGEeDlL/4zaF5RuZMp9rDGQskQtr5597rjhPiJbgIzOBXNYdfq+MP/9QyI
+d+NoQRQgdPODYEK+9RgtpneKtz4ap6e/jQU1fKTuViuqUSAVV/vocL+PV9LGQxg
HIPHKQn+rE0tQ8N6/R3asdG+mK4Ow3K8T5O7TWxq/MGjLpxhAoLQ1t0AVVLjnOh6
Yx8bXBGS61MQhcuNI2+X6PwZ8GHr/9n1rf1z/9fR2nYun4/XHCUEUCjuvxCZGbJb
viYo3nexdtA/dsRYbLYW8x5yzO6mZ7k90c3bvmBKkVjhAtWTjv2o6KtntR99oo5c
nQIDAQAB -----END PUBLIC KEY-----

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

Communication with the Partner

Example API response body:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImN0eSI6ImFwcGxpY2F0aW9uL2pzb24iLCJraWQiOiJBbXowZzNRR3NPaUZPcnkzeWlzYTlEaE5EQ01QUlJncWRhYjNxSnQ0enRNIn0.eyJpbmNvbWUiOnsiY3VycmVuY3kiOiJQTE4iLCJhbW91bnQiOjEwfSwib3V0Y29tZSI6eyJjdXJyZW5jeSI6IkVVUiIsImFtb3VudCI6Mi4zfSwidG9rZW4iOiJmZTA1NTM3MGE2NmU0M2RjZjc2MmUwMjVlNmY4ZGZkZmM3NGRkZjE1N2M4MmMwMzEyY2FlYzIwMjAxOTJkYzNjZGVhMmUwN2I2ZjA2Mzc1ZjRkYzI2YmFlNTJhNjVlYTE2MjczMjRhZTFhM2IxZDEwNzZjOTRhNmNmMzk0ZjZjZCIsImV4cGlyYXRpb25EYXRlIjoiMjAyMy0xMi0xMiAxMzo1MDowNCIsInZhbGlkRGlzY291bnRDb2RlIjpmYWxzZSwicmF0ZVNjYWxpbmciOjEsImxpbWl0TmF0aXZlQW1vdW50RXhjZWVkZWQiOmZhbHNlLCJ0cmFuc2FjdGlvbkxpbWl0RXhjZWVkZWQiOmZhbHNlLCJuZWdvdGlhdGVSYXRlIjpmYWxzZSwicmF0ZVNlbGwiOjEsInJhdGVCdXkiOjQuMzUxNCwiaGFzUGVuZGluZ1RyYW5zYWN0aW9ucyI6dHJ1ZSwiZXhjaGFuZ2VSYXRlIjo0LjM1MTQsImV4Y2hhbmdlUmF0ZVdpdGhvdXRDb2RlIjo0LjM1MTQsImV4Y2hhbmdlRGlzY291bnRDb2RlU2F2ZSI6MH0.GOLS7bl2YwPce7TosB8YQeoxLBwLdBEjI0DNFF7hDsoU5V3NAHf6tgsLhXb2O9OKeYDeBfKzXDvOKxiUWi8ktuSs4TqtsneDD64DN531BrMc1dPe3iUtx-83k7kQjCkVj_X89DqwOv8Xn3hQwBrt76qu2q-bmAeQjOxAjSUvqtp1j2J7CGAAzAH0HhmmxLk6_GKvmpwdXNl5zxT7MAw1SY1TNE9nHHJ66E1xsu6Yewy_rmcnsxC6f1fb_evVeYO97mJQ4yRYk_oW5CLJ_UkuxB3E9wqnoy4ovjxjjkISx8mgFJZ0TQdkXlEd84CBPilhEZhSHKE9au9VU9L_cez6hg```

> Response headers

> `HTTP/1.1 201 Created`<br>
> `Content-Type: application/jose+json`

> JWS Header

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

JWS Payload

{
  "from": {
    "amount": {
      "currency": "PLN",
      "value": 10
    }
  },
  "to": {
    "amount": {
      "currency": "EUR",
      "value": 2.3
    }
  },
  "token": "fe055370a66e43dcf762e025e6f8dfdfc74ddf157c82c0312caec2020192dc3cdea2e07b6f06375f4dc26bae52a65ea1627324ae1a3b1d1076c94a6cf394f6cd",
  "expirationDate": "2023-12-12 13:50:04",
  "validDiscountCode": false,
  "rateScaling": 1,
  "limitNativeAmountExceeded": false,
  "transactionLimitExceeded": false,
  "negotiateRate": false,
  "rateSell": 1,
  "rateBuy": 4.3514,
  "hasPendingTransactions": true,
  "exchangeRate": 4.3514,
  "exchangeRateWithoutCode": 4.3514,
  "exchangeDiscountCodeSave": 0
}

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

Generating a public key

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:

  1. Open the console
  2. Depending on distribution, install openssl using package manager with given command:

Generating the key

  1. Open the console
  2. 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
  3. 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:

  1. Open utheTerminal
  2. To install openssl it is required to install a package manager for macOS called homebrew:
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  3. To install openssl using package manager enter the following command:
    brew install libressl

Generating the key

  1. Open the Terminal
  2. 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
  3. 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:

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

Generating the key

  1. Navigate to extracted folder libressl-2.5.5-windows/x86/
  2. Run openssl.exe
  3. 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
  4. The public key is in "public-key.pem" file in the current directory

Private key security

Store the private key in a secure location like the HSM (Hardware Security Module). If a hardware-based protection method is unavailable, you should use an operating system secure private key store. Securely storing your private key will reduce the likelihood of its compromise.

Adding public key

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-----"
     }

Response headers:

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

Response body:

{
  "kid": "lpSoenUSsyxPtZlkP3tGLH9iPLZn1L4zf0G9jUhX3zQ",
  "status": "INACTIVE"
}

To enable secure communication between Conotoxia Pay 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>
 It must contain a Bearer access token. For more information, see Generating access token.
Content-Type application/json

Request body

PublicKey object containing data on the public key

Field name Type Required Description
pem String YES Partner’s public key.
sampleData SampleData NO Object containing sample texts for public key verification.

Object SampleData containing sample texts for public key verification

Sample request with optional sampleData field:

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=="
        }
     }
Field name Type Required Description
decodedText String YES Sample text sent to verify the accuracy of the public key.
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 TAK 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

API errors

The POST /public_keys method can return the following business errors:

Getting public keys

curl -X GET \
     -H "Authorization: Bearer M1ODU2ZDI5NzU3ZWFkYTRjMjEyMTIwNmRiNmQ2MjdmM" \
     "<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

Response body:

{
 "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.AVbO7pKOwd_wDBTuC9TriU4wafUxuXJ1G35REfhbgzSH0HvoIeymGsb5ItdUmFXzLnQqV5OsptawinIErNzx4DW-RUsheijJztenHHxOPlsE3m1LMfzJqg78qVYnzZatWRlNT86u0O-DIvfcdWcL0MGQDpTxs2V8IJCJWIZqEDm-V3WpUcjgMuqhj_jl-GL1TRhnLZjZkW8YwfvLNBXfpcvfyI58Q4mnhaMsmw6ikgjI3ocIhuGW-uXvA2E-gJxmaoN-O3BqG1u2XWKtWOA_sRf6-0P8PTI2JA-AToUjdK9yd-lcufIkyJvFUYf3XmzgV8uoCH11tCM3gd-Vp-_kfg

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>
 It must contain a Bearer access token. For more information, see Generating access token.

Response body

data object containing the list of added public keys

Field name Type Required Description
data Array NO 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 Pay

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.

API errors

The GET /v2/public_keys method can only return technical errors.

Getting Conotoxia Pay key

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

Response headers:

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

Response body:

{
 "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 Pay system it is necessary to have a public key of the Conotoxia Pay system. To obtain the key, the GET /jwks resource should be used.

Resource

GET <CONOTOXIA_HOST>/jwks See server addresses

Request headers

Name Value Remarks
Authorization
Bearer <access_token>
 It must contain a Bearer access token. For more information, see Generating access token.

Response body

PublicKeys object containing the list of public keys of the Conotoxia Pay 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 Pay

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

The GET /jwks method can only return technical errors.

Currency Currency code Number of digits after the decimal separator Minimum currency units for a transaction
Dirham (United Arab Emirates) AED 2 1
Australian dollar AUD 2 1
Bulgarian lev BGN 2 1
Canadaian Dollar CAD 2 1
Swiss franc CHF 2 1
Chinese yuan CNY 2 1
Czech Republic Koruna CZK 2 10
Denmark Krone DKK 2 10
Euro EUR 2 1
Bristish pound GBP 2 1
Hong Kong dollar HKD 2 1
Hungarian forint HUF 0 100
Israeli new shekel ILS 2 1
Japanese yen JPY 0 100
Mexico Peso MXN 2 1
Norwegian krone NOK 2 10
New Zealand dollar NZD 2 1
Polish zloty PLN 2 1
Romanian leu RON 2 1
Swedish krone SEK 2 10
Singapore dollar SGD 2 1
Turkish lira TRY 2 1
United States dollar USD 2 1
South Africa rand ZAR 2 1
Thailand baht THB 2 100
Serbian dinar RSD 2 10
cURL unsigned cURL signed